Package org.apache.druid.segment

Interface VirtualColumn

All Superinterfaces:

Cacheable

All Known Implementing Classes:

ExpressionVirtualColumn, FallbackVirtualColumn, ListFilteredVirtualColumn, NestedFieldVirtualColumn, NestedMergeVirtualColumn, NestedObjectVirtualColumn, PrefixFilteredVirtualColumn, RegexFilteredVirtualColumn, SettableLongVirtualColumn, SpecializedExpressionVirtualColumn

public interface VirtualColumn
extends Cacheable

Virtual columns are "views" created over a ColumnSelectorFactory or ColumnSelector. They can potentially draw from multiple underlying columns, although they always present themselves as if they were a single column. A virtual column object will be shared amongst threads and must be thread safe. The selectors returned from the various makeXXXSelector methods need not be thread safe.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	VirtualColumn.EquivalenceKey

Method Summary

Modifier and Type	Method	Description
default boolean	canVectorize(ColumnInspector inspector)
ColumnCapabilities	capabilities(String columnName)	Deprecated.
default ColumnCapabilities	capabilities(ColumnInspector inspector, String columnName)	Return the ColumnCapabilities which best describe the optimal selector to read from this virtual column.
default VirtualColumn.EquivalenceKey	getEquivalanceKey()	Returns a key used for "equivalence" comparisons, for checking if some virtual column is equivalent to some other virtual column, regardless of the output name.
default ColumnIndexSupplier	getIndexSupplier(String columnName, ColumnIndexSelector columnIndexSelector)	Get the ColumnIndexSupplier of the specified virtual column, with the assistance of a ColumnSelector to allow reading things from segments.
String	getOutputName()	Output name of this column.
default ColumnValueSelector<?>	makeColumnValueSelector(String columnName, ColumnSelectorFactory factory)	Deprecated. use makeColumnValueSelector(String, ColumnSelectorFactory, ColumnSelector, ReadableOffset)
default ColumnValueSelector<?>	makeColumnValueSelector(String columnName, ColumnSelectorFactory columnSelectorFactory, ColumnSelector columnSelector, ReadableOffset offset)	Builds a selector corresponding to this virtual column.
default ColumnValueSelector<?>	makeColumnValueSelector(String columnName, ColumnSelector columnSelector, ReadableOffset offset)	Deprecated. use makeColumnValueSelector(String, ColumnSelectorFactory, ColumnSelector, ReadableOffset)
default DimensionSelector	makeDimensionSelector(DimensionSpec dimensionSpec, ColumnSelectorFactory factory)	Deprecated. use makeDimensionSelector(DimensionSpec, ColumnSelectorFactory, ColumnSelector, ReadableOffset)
default DimensionSelector	makeDimensionSelector(DimensionSpec dimensionSpec, ColumnSelectorFactory columnSelectorFactory, ColumnSelector columnSelector, ReadableOffset offset)	Build a selector corresponding to this virtual column.
default DimensionSelector	makeDimensionSelector(DimensionSpec dimensionSpec, ColumnSelector columnSelector, ReadableOffset offset)	Deprecated. use makeDimensionSelector(DimensionSpec, ColumnSelectorFactory, ColumnSelector, ReadableOffset)
default GroupByVectorColumnSelector	makeGroupByVectorColumnSelector(String columnName, VectorColumnSelectorFactory factory, DeferExpressionDimensions deferExpressionDimensions)	Returns a group-by selector.
default MultiValueDimensionVectorSelector	makeMultiValueVectorDimensionSelector(DimensionSpec dimensionSpec, ColumnSelector columnSelector, ReadableVectorOffset offset)	Deprecated. use makeMultiValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)
default MultiValueDimensionVectorSelector	makeMultiValueVectorDimensionSelector(DimensionSpec dimensionSpec, VectorColumnSelectorFactory factory)	Deprecated. use makeMultiValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)
default MultiValueDimensionVectorSelector	makeMultiValueVectorDimensionSelector(DimensionSpec dimensionSpec, VectorColumnSelectorFactory factory, ColumnSelector columnSelector, ReadableVectorOffset offset)	Build a selector corresponding to this virtual column.
default SingleValueDimensionVectorSelector	makeSingleValueVectorDimensionSelector(DimensionSpec dimensionSpec, ColumnSelector columnSelector, ReadableVectorOffset offset)	Deprecated. use makeSingleValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)
default SingleValueDimensionVectorSelector	makeSingleValueVectorDimensionSelector(DimensionSpec dimensionSpec, VectorColumnSelectorFactory factory)	Deprecated. use makeSingleValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)
default SingleValueDimensionVectorSelector	makeSingleValueVectorDimensionSelector(DimensionSpec dimensionSpec, VectorColumnSelectorFactory factory, ColumnSelector columnSelector, ReadableVectorOffset offset)	Build a selector corresponding to this virtual column.
default VectorObjectSelector	makeVectorObjectSelector(String columnName, ColumnSelector columnSelector, ReadableVectorOffset offset)	Deprecated. use makeVectorObjectSelector(String, ColumnSelector, ReadableVectorOffset)
default VectorObjectSelector	makeVectorObjectSelector(String columnName, VectorColumnSelectorFactory factory)	Deprecated. use makeVectorObjectSelector(String, ColumnSelector, ReadableVectorOffset)
default VectorObjectSelector	makeVectorObjectSelector(String columnName, VectorColumnSelectorFactory factory, ColumnSelector columnSelector, ReadableVectorOffset offset)	Build a selector corresponding to this virtual column.
default VectorValueSelector	makeVectorValueSelector(String columnName, ColumnSelector columnSelector, ReadableVectorOffset offset)	Deprecated. use makeVectorValueSelector(String, ColumnSelector, ReadableVectorOffset)
default VectorValueSelector	makeVectorValueSelector(String columnName, VectorColumnSelectorFactory factory)	Deprecated. use makeVectorValueSelector(String, ColumnSelector, ReadableVectorOffset)
default VectorValueSelector	makeVectorValueSelector(String columnName, VectorColumnSelectorFactory factory, ColumnSelector columnSelector, ReadableVectorOffset offset)	Build a selector corresponding to this virtual column.
List<String>	requiredColumns()	Returns a list of columns that this virtual column will access.
default VirtualColumn	rewriteRequiredColumns(Map<String,String> columnRewrites)	Return a copy of this virtual column that is identical to this virtual column except that it operates on different columns, based on a renaming map where the key is the column to be renamed and the value is the new column.
default boolean	supportsRequiredRewrite()	Returns true if the virtual column supports rewriteRequiredColumns(Map)
default SelectableColumn	toSelectableColumn(ColumnIndexSelector columnSelector)	Produces a SelectableColumn from this virtual column.
default boolean	usesDotNotation()	Indicates that this virtual column can be referenced with dot notation.

Methods inherited from interface org.apache.druid.java.util.common.Cacheable

getCacheKey

Method Details

getOutputName

String getOutputName()

Output name of this column.

Returns:

name

makeDimensionSelector

default DimensionSelector makeDimensionSelector(DimensionSpec dimensionSpec,
 ColumnSelectorFactory columnSelectorFactory,
 @Nullable
 ColumnSelector columnSelector,
 @Nullable
 ReadableOffset offset)

Build a selector corresponding to this virtual column. The virtual column is expected to apply any necessary DimensionSpec.decorate(DimensionSelector) or DimensionSpec.getExtractionFn() from the dimensionSpec.

Parameters:

dimensionSpec - spec the column was referenced with. Also provides the name that the virtual column was referenced with, which is useful if this column uses dot notation.

columnSelectorFactory - object for fetching underlying selectors.

columnSelector - object for fetching underlying columns, if available. Generally only available for regular segments.

offset - offset to use with underlying columns. Available only if columnSelector is available.

makeDimensionSelector

@Deprecated
default DimensionSelector makeDimensionSelector(DimensionSpec dimensionSpec,
 ColumnSelectorFactory factory)

Deprecated.

use makeDimensionSelector(DimensionSpec, ColumnSelectorFactory, ColumnSelector, ReadableOffset)

makeDimensionSelector

@Deprecated
@Nullable
default DimensionSelector makeDimensionSelector(DimensionSpec dimensionSpec,
 ColumnSelector columnSelector,
 ReadableOffset offset)

Deprecated.

use makeDimensionSelector(DimensionSpec, ColumnSelectorFactory, ColumnSelector, ReadableOffset)

makeColumnValueSelector

default ColumnValueSelector<?> makeColumnValueSelector(String columnName,
 ColumnSelectorFactory columnSelectorFactory,
 @Nullable
 ColumnSelector columnSelector,
 @Nullable
 ReadableOffset offset)

Builds a selector corresponding to this virtual column.

Parameters:

columnName - name the column was referenced with, which is useful if this column uses dot notation.

columnSelectorFactory - object for fetching underlying selectors.

columnSelector - object for fetching underlying columns, if available. Generally only available for regular segments.

offset - offset to use with underlying columns. Available only if columnSelector is available.

makeColumnValueSelector

@Deprecated
default ColumnValueSelector<?> makeColumnValueSelector(String columnName,
 ColumnSelectorFactory factory)

Deprecated.

use makeColumnValueSelector(String, ColumnSelectorFactory, ColumnSelector, ReadableOffset)

makeColumnValueSelector

@Deprecated
@Nullable
default ColumnValueSelector<?> makeColumnValueSelector(String columnName,
 ColumnSelector columnSelector,
 ReadableOffset offset)

Deprecated.

use makeColumnValueSelector(String, ColumnSelectorFactory, ColumnSelector, ReadableOffset)

canVectorize

default boolean canVectorize(ColumnInspector inspector)

makeSingleValueVectorDimensionSelector

default SingleValueDimensionVectorSelector makeSingleValueVectorDimensionSelector(DimensionSpec dimensionSpec,
 VectorColumnSelectorFactory factory,
 ColumnSelector columnSelector,
 ReadableVectorOffset offset)

Build a selector corresponding to this virtual column. The virtual column is expected to apply any necessary DimensionSpec.decorate(DimensionSelector) or DimensionSpec.getExtractionFn() from the dimensionSpec.

Parameters:

dimensionSpec - spec the column was referenced with. Also provides the name that the virtual column was referenced with, which is useful if this column uses dot notation.

factory - object for fetching underlying selectors.

columnSelector - object for fetching underlying columns.

offset - offset to use with underlying columns.

makeSingleValueVectorDimensionSelector

@Deprecated
default SingleValueDimensionVectorSelector makeSingleValueVectorDimensionSelector(DimensionSpec dimensionSpec,
 VectorColumnSelectorFactory factory)

Deprecated.

use makeSingleValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)

makeSingleValueVectorDimensionSelector

@Deprecated
@Nullable
default SingleValueDimensionVectorSelector makeSingleValueVectorDimensionSelector(DimensionSpec dimensionSpec,
 ColumnSelector columnSelector,
 ReadableVectorOffset offset)

Deprecated.

use makeSingleValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)

makeMultiValueVectorDimensionSelector

default MultiValueDimensionVectorSelector makeMultiValueVectorDimensionSelector(DimensionSpec dimensionSpec,
 VectorColumnSelectorFactory factory,
 ColumnSelector columnSelector,
 ReadableVectorOffset offset)

Build a selector corresponding to this virtual column. The virtual column is expected to apply any necessary DimensionSpec.decorate(DimensionSelector) or DimensionSpec.getExtractionFn() from the dimensionSpec.

Parameters:

dimensionSpec - spec the column was referenced with. Also provides the name that the virtual column was referenced with, which is useful if this column uses dot notation.

factory - object for fetching underlying selectors.

columnSelector - object for fetching underlying columns, if available. Generally only available for regular segments.

offset - offset to use with underlying columns. Available only if columnSelector is available.

makeMultiValueVectorDimensionSelector

@Deprecated
default MultiValueDimensionVectorSelector makeMultiValueVectorDimensionSelector(DimensionSpec dimensionSpec,
 VectorColumnSelectorFactory factory)

Deprecated.

use makeMultiValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)

makeMultiValueVectorDimensionSelector

@Nullable
@Deprecated
default MultiValueDimensionVectorSelector makeMultiValueVectorDimensionSelector(DimensionSpec dimensionSpec,
 ColumnSelector columnSelector,
 ReadableVectorOffset offset)

Deprecated.

use makeMultiValueVectorDimensionSelector(DimensionSpec, ColumnSelector, ReadableVectorOffset)

makeVectorValueSelector

default VectorValueSelector makeVectorValueSelector(String columnName,
 VectorColumnSelectorFactory factory,
 ColumnSelector columnSelector,
 ReadableVectorOffset offset)

Build a selector corresponding to this virtual column. The virtual column is expected to apply any necessary DimensionSpec.decorate(DimensionSelector) or DimensionSpec.getExtractionFn() from the dimensionSpec.

Parameters:

columnName - name the column was referenced with, which is useful if this column uses dot notation.

factory - object for fetching underlying selectors.

columnSelector - object for fetching underlying columns.

offset - offset to use with underlying columns.

makeVectorValueSelector

@Deprecated
default VectorValueSelector makeVectorValueSelector(String columnName,
 VectorColumnSelectorFactory factory)

Deprecated.

use makeVectorValueSelector(String, ColumnSelector, ReadableVectorOffset)

makeVectorValueSelector

@Nullable
@Deprecated
default VectorValueSelector makeVectorValueSelector(String columnName,
 ColumnSelector columnSelector,
 ReadableVectorOffset offset)

Deprecated.

use makeVectorValueSelector(String, ColumnSelector, ReadableVectorOffset)

makeVectorObjectSelector

default VectorObjectSelector makeVectorObjectSelector(String columnName,
 VectorColumnSelectorFactory factory,
 ColumnSelector columnSelector,
 ReadableVectorOffset offset)

Build a selector corresponding to this virtual column. The virtual column is expected to apply any necessary DimensionSpec.decorate(DimensionSelector) or DimensionSpec.getExtractionFn() from the dimensionSpec.

Parameters:

columnName - name the column was referenced with, which is useful if this column uses dot notation.

factory - object for fetching underlying selectors.

columnSelector - object for fetching underlying columns, if available. Generally only available for regular segments.

offset - offset to use with underlying columns. Available only if columnSelector is available.

makeVectorObjectSelector

@Deprecated
default VectorObjectSelector makeVectorObjectSelector(String columnName,
 VectorColumnSelectorFactory factory)

Deprecated.

use makeVectorObjectSelector(String, ColumnSelector, ReadableVectorOffset)

makeVectorObjectSelector

@Nullable
@Deprecated
default VectorObjectSelector makeVectorObjectSelector(String columnName,
 ColumnSelector columnSelector,
 ReadableVectorOffset offset)

Deprecated.

use makeVectorObjectSelector(String, ColumnSelector, ReadableVectorOffset)

makeGroupByVectorColumnSelector

@Nullable
default GroupByVectorColumnSelector makeGroupByVectorColumnSelector(String columnName,
 VectorColumnSelectorFactory factory,
 DeferExpressionDimensions deferExpressionDimensions)

Returns a group-by selector. Allows virtual columns to control their own grouping behavior.

Parameters:

columnName - column name

factory - column selector factory

deferExpressionDimensions - active value of GroupByQueryConfig.CTX_KEY_DEFER_EXPRESSION_DIMENSIONS

Returns:

selector, or null if this virtual column does not have a specialized one

capabilities

@Deprecated
ColumnCapabilities capabilities(String columnName)

Deprecated.

This method is deprecated in favor of capabilities(ColumnInspector, String), which should be used whenever possible and can support virtual column implementations that need to inspect other columns as inputs. This is a fallback implementation to return the capabilities of this virtual column, which includes a type that corresponds to the best performing base selector supertype (e. g. BaseLongColumnValueSelector) of the object, returned from makeColumnValueSelector(String, ColumnSelectorFactory). May vary based on columnName if this column uses dot notation.

Parameters:

columnName - the name this virtual column was referenced with

Returns:

capabilities, must not be null

capabilities

@Nullable
default ColumnCapabilities capabilities(ColumnInspector inspector,
 String columnName)

Return the ColumnCapabilities which best describe the optimal selector to read from this virtual column.

The ColumnInspector (most likely corresponding to an underlying ColumnSelectorFactory of a query) allows the virtual column to consider this information if necessary to compute its output type details.

Examples of this include the ExpressionVirtualColumn, which takes input from other columns and uses the ColumnInspector to infer the output type of expressions based on the types of the inputs.

Parameters:

inspector - column inspector to provide additional information of other available columns

columnName - the name this virtual column was referenced with

Returns:

capabilities, or null if the column should be treated as if it doesn't exist.

requiredColumns

List<String> requiredColumns()

Returns a list of columns that this virtual column will access. This may include the names of other virtual columns. May be empty if a virtual column doesn't access any underlying columns. Does not pass columnName because there is an assumption that the list of columns needed by a dot-notation supporting virtual column will not vary based on the columnName.

Returns:

column names

supportsRequiredRewrite

default boolean supportsRequiredRewrite()

Returns true if the virtual column supports rewriteRequiredColumns(Map)

rewriteRequiredColumns

default VirtualColumn rewriteRequiredColumns(Map<String,String> columnRewrites)

Return a copy of this virtual column that is identical to this virtual column except that it operates on different columns, based on a renaming map where the key is the column to be renamed and the value is the new column. Callers should check supportsRequiredRewrite() first to ensure that this method is supported.

Parameters:

columnRewrites - Column rewrite map

Returns:

Copy of this virtual column that operates on new columns based on the rewrite map

usesDotNotation

default boolean usesDotNotation()

Indicates that this virtual column can be referenced with dot notation. For example, a virtual column named "foo" could be referred to as "foo.bar" with the Cursor it is registered with. In that case, init will be called with columnName "foo.bar" rather than "foo".

Returns:

whether to use dot notation

toSelectableColumn

default SelectableColumn toSelectableColumn(ColumnIndexSelector columnSelector)

Produces a SelectableColumn from this virtual column. This allows the virtual column to offer specialized interfaces, such as NestedColumnTypeInspector or NestedColumnSelectorFactory. These interfaces may be used by query objects, including other virtual columns, to perform queries in a more efficient manner.

Parameters:

columnSelector - selector for underlying columns and indexes. Cannot be used during execution of this method, but can be stored for later usage.

getIndexSupplier

@Nullable
default ColumnIndexSupplier getIndexSupplier(String columnName,
 ColumnIndexSelector columnIndexSelector)

Get the ColumnIndexSupplier of the specified virtual column, with the assistance of a ColumnSelector to allow reading things from segments. Returns null if the virtual column wants to act like a missing column. Returns NoIndexesColumnIndexSupplier.getInstance() if the virtual column does not support indexes and wants cursor-based filtering.

getEquivalanceKey

@Nullable
default VirtualColumn.EquivalenceKey getEquivalanceKey()

Returns a key used for "equivalence" comparisons, for checking if some virtual column is equivalent to some other virtual column, regardless of the output name. If this method returns null, it does not participate in equivalence comparisons.

See Also:

• VirtualColumns.findEquivalent(VirtualColumns, VirtualColumn)