Package org.apache.calcite.rel.metadata

Class RelMetadataQuery

java.lang.Object

org.apache.calcite.rel.metadata.RelMetadataQueryBase

org.apache.calcite.rel.metadata.RelMetadataQuery

public class RelMetadataQuery
extends RelMetadataQueryBase

RelMetadataQuery provides a strongly-typed facade on top of RelMetadataProvider for the set of relational expression metadata queries defined as standard within Calcite. The Javadoc on these methods serves as their primary specification.

To add a new standard query Xyz to this interface, follow these steps:

1. Add a static method getXyz specification to this class.
2. Add unit tests to org.apache.calcite.test.RelMetadataTest.
3. Write a new provider class RelMdXyz in this package. Follow the pattern from an existing class such as RelMdColumnOrigins, overloading on all of the logical relational expressions to which the query applies.
4. Add a SOURCE static member, similar to RelMdColumnOrigins.SOURCE.
5. Register the SOURCE object in DefaultRelMetadataProvider.
6. Get unit tests working.

Because relational expression metadata is extensible, extension projects can define similar facades in order to specify access to custom metadata. Please do not add queries here (nor on RelNode) which lack meaning outside of your extension.

Besides adding new metadata queries, extension projects may need to add custom providers for the standard queries in order to handle additional relational expressions (either logical or physical). In either case, the process is the same: write a reflective provider and chain it on to an instance of DefaultRelMetadataProvider, pre-pending it to the default providers. Then supply that instance to the planner via the appropriate plugin mechanism.

Field Summary

Fields inherited from class org.apache.calcite.rel.metadata.RelMetadataQueryBase

map, metadataProvider, THREAD_PROVIDERS

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	RelMetadataQuery()	Creates the instance with JaninoRelMetadataProvider instance from RelMetadataQueryBase.THREAD_PROVIDERS and EMPTY as a prototype.
	RelMetadataQuery(MetadataHandlerProvider provider)	Create a RelMetadataQuery with a given MetadataHandlerProvider.

Method Summary

Modifier and Type	Method	Description
@Nullable Boolean	areColumnsUnique(RelNode rel, ImmutableBitSet columns)	Returns the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(ImmutableBitSet, boolean) statistic.
@Nullable Boolean	areColumnsUnique(RelNode rel, ImmutableBitSet columns, boolean ignoreNulls)	Returns the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(ImmutableBitSet, boolean) statistic.
@Nullable Boolean	areRowsUnique(RelNode rel)	Returns whether the rows of a given relational expression are distinct.
@Nullable Boolean	areRowsUnique(RelNode rel, boolean ignoreNulls)	Returns whether the rows of a given relational expression are distinct, optionally ignoring NULL values.
@Nullable com.google.common.collect.ImmutableList<RelCollation>	collations(RelNode rel)	Returns the BuiltInMetadata.Collation.collations() statistic.
@Nullable Double	cumulativeMemoryWithinPhase(RelNode rel)	Returns the BuiltInMetadata.Memory.cumulativeMemoryWithinPhase() statistic.
@Nullable Double	cumulativeMemoryWithinPhaseSplit(RelNode rel)	Returns the BuiltInMetadata.Memory.cumulativeMemoryWithinPhaseSplit() statistic.
RelDistribution	distribution(RelNode rel)	Returns the BuiltInMetadata.Distribution.distribution() statistic.
RexNode	expand(RelNode rel, int column, BuiltInMetadata.Measure.Context context)	Returns the BuiltInMetadata.Measure.expand(int, BuiltInMetadata.Measure.Context) statistic.
@Nullable RelOptPredicateList	getAllPredicates(RelNode rel)	Returns the BuiltInMetadata.AllPredicates.getAllPredicates() statistic.
@Nullable List<@Nullable Double>	getAverageColumnSizes(RelNode rel)	Returns the BuiltInMetadata.Size.averageColumnSizes() statistic.
List<@Nullable Double>	getAverageColumnSizesNotNull(RelNode rel)	As getAverageColumnSizes(org.apache.calcite.rel.RelNode) but never returns a null list, only ever a list of nulls.
@Nullable Double	getAverageRowSize(RelNode rel)	Returns the BuiltInMetadata.Size.averageRowSize() statistic.
@Nullable RelColumnOrigin	getColumnOrigin(RelNode rel, int column)	Determines the origin of a column.
@Nullable Set<RelColumnOrigin>	getColumnOrigins(RelNode rel, int column)	Returns the BuiltInMetadata.ColumnOrigin.getColumnOrigins(int) statistic.
@Nullable RelOptCost	getCumulativeCost(RelNode rel)	Returns the BuiltInMetadata.CumulativeCost.getCumulativeCost() statistic.
@Nullable Double	getDistinctRowCount(RelNode rel, ImmutableBitSet groupKey, @Nullable RexNode predicate)	Returns the BuiltInMetadata.DistinctRowCount.getDistinctRowCount(ImmutableBitSet, RexNode) statistic.
@Nullable RelDistribution	getDistribution(RelNode rel)	Returns the BuiltInMetadata.Distribution.distribution() statistic.
@Nullable Set<RexNode>	getExpressionLineage(RelNode rel, RexNode expression)	Determines the origin of a column.
@Nullable RelOptCost	getLowerBoundCost(RelNode rel, VolcanoPlanner planner)	Returns the lower bound cost of a RelNode.
@Nullable Double	getMaxRowCount(RelNode rel)	Returns the BuiltInMetadata.MaxRowCount.getMaxRowCount() statistic.
@Nullable Double	getMinRowCount(RelNode rel)	Returns the BuiltInMetadata.MinRowCount.getMinRowCount() statistic.
@Nullable com.google.common.collect.Multimap<Class<? extends RelNode>,RelNode>	getNodeTypes(RelNode rel)	Returns the BuiltInMetadata.NodeTypes.getNodeTypes() statistic.
@Nullable RelOptCost	getNonCumulativeCost(RelNode rel)	Returns the BuiltInMetadata.NonCumulativeCost.getNonCumulativeCost() statistic.
@Nullable Double	getPercentageOriginalRows(RelNode rel)	Returns the BuiltInMetadata.PercentageOriginalRows.getPercentageOriginalRows() statistic.
@Nullable Double	getPopulationSize(RelNode rel, ImmutableBitSet groupKey)	Returns the BuiltInMetadata.PopulationSize.getPopulationSize(ImmutableBitSet) statistic.
RelOptPredicateList	getPulledUpPredicates(RelNode rel)	Returns the BuiltInMetadata.Predicates.getPredicates() statistic.
Double	getRowCount(RelNode rel)	Returns the BuiltInMetadata.RowCount.getRowCount() statistic.
@Nullable Double	getSelectivity(RelNode rel, @Nullable RexNode predicate)	Returns the BuiltInMetadata.Selectivity.getSelectivity(RexNode) statistic.
@Nullable RelOptTable	getTableOrigin(RelNode rel)	Determines the origin of a RelNode, provided it maps to a single table, optionally with filtering and projection.
@Nullable Set<RexTableInputRef.RelTableRef>	getTableReferences(RelNode rel)	Determines the tables used by a plan.
@Nullable Set<ImmutableBitSet>	getUniqueKeys(RelNode rel)	Returns the BuiltInMetadata.UniqueKeys.getUniqueKeys(boolean) statistic.
@Nullable Set<ImmutableBitSet>	getUniqueKeys(RelNode rel, boolean ignoreNulls)	Returns the BuiltInMetadata.UniqueKeys.getUniqueKeys(boolean) statistic.
static RelMetadataQuery	instance()	Returns an instance of RelMetadataQuery.
@Nullable Boolean	isEmpty(RelNode relNode)	Returns whether the return rows of a given relational expression are empty.
@Nullable Boolean	isMeasure(RelNode rel, int column)	Returns the BuiltInMetadata.Measure.isMeasure(int) statistic.
@Nullable Boolean	isPhaseTransition(RelNode rel)	Returns the BuiltInMetadata.Parallelism.isPhaseTransition() statistic.
Boolean	isVisibleInExplain(RelNode rel, SqlExplainLevel explainLevel)	Returns the BuiltInMetadata.ExplainVisibility.isVisibleInExplain(SqlExplainLevel) statistic.
@Nullable Double	memory(RelNode rel)	Returns the BuiltInMetadata.Memory.memory() statistic.
@Nullable Integer	splitCount(RelNode rel)	Returns the BuiltInMetadata.Parallelism.splitCount() statistic.

Methods inherited from class org.apache.calcite.rel.metadata.RelMetadataQueryBase

clearCache, handler, initialHandler, revise, revise

Methods inherited from class java.lang.Object

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

Constructor Details

RelMetadataQuery

protected RelMetadataQuery()

Creates the instance with JaninoRelMetadataProvider instance from RelMetadataQueryBase.THREAD_PROVIDERS and EMPTY as a prototype.

RelMetadataQuery

public RelMetadataQuery(MetadataHandlerProvider provider)

Create a RelMetadataQuery with a given MetadataHandlerProvider.

Parameters:

provider - The provider to use for construction.

Method Details

instance

public static RelMetadataQuery instance()

Returns an instance of RelMetadataQuery. It ensures that cycles do not occur while computing metadata.

getNodeTypes

public @Nullable com.google.common.collect.Multimap<Class<? extends RelNode>,RelNode> getNodeTypes(RelNode rel)

Returns the BuiltInMetadata.NodeTypes.getNodeTypes() statistic.

Parameters:

rel - the relational expression

getRowCount

public Double getRowCount(RelNode rel)

Returns the BuiltInMetadata.RowCount.getRowCount() statistic.

Parameters:

rel - the relational expression

Returns:

estimated row count, or null if no reliable estimate can be determined

getMaxRowCount

public @Nullable Double getMaxRowCount(RelNode rel)

Returns the BuiltInMetadata.MaxRowCount.getMaxRowCount() statistic.

Parameters:

rel - the relational expression

Returns:

max row count

getMinRowCount

public @Nullable Double getMinRowCount(RelNode rel)

Returns the BuiltInMetadata.MinRowCount.getMinRowCount() statistic.

Parameters:

rel - the relational expression

Returns:

min row count

isEmpty

public @Nullable Boolean isEmpty(RelNode relNode)

Returns whether the return rows of a given relational expression are empty.

Parameters:

relNode - the relational expression

Returns:

true or false depending on whether the return rows are empty, or null if not enough information is available to make that determination

getCumulativeCost

public @Nullable RelOptCost getCumulativeCost(RelNode rel)

Returns the BuiltInMetadata.CumulativeCost.getCumulativeCost() statistic.

Parameters:

rel - the relational expression

Returns:

estimated cost, or null if no reliable estimate can be determined

getNonCumulativeCost

public @Nullable RelOptCost getNonCumulativeCost(RelNode rel)

Returns the BuiltInMetadata.NonCumulativeCost.getNonCumulativeCost() statistic.

Parameters:

rel - the relational expression

Returns:

estimated cost, or null if no reliable estimate can be determined

getPercentageOriginalRows

public @Nullable Double getPercentageOriginalRows(RelNode rel)

Returns the BuiltInMetadata.PercentageOriginalRows.getPercentageOriginalRows() statistic.

Parameters:

rel - the relational expression

Returns:

estimated percentage (between 0.0 and 1.0), or null if no reliable estimate can be determined

getColumnOrigins

public @Nullable Set<RelColumnOrigin> getColumnOrigins(RelNode rel,
 int column)

Returns the BuiltInMetadata.ColumnOrigin.getColumnOrigins(int) statistic.

Parameters:

rel - the relational expression

column - 0-based ordinal for output column of interest

Returns:

set of origin columns, or null if this information cannot be determined (whereas empty set indicates definitely no origin columns at all)

getColumnOrigin

public @Nullable RelColumnOrigin getColumnOrigin(RelNode rel,
 int column)

Determines the origin of a column.

Parameters:

rel - the RelNode of the column

column - the offset of the column whose origin we are trying to determine

Returns:

the origin of a column

See Also:

• getColumnOrigins(org.apache.calcite.rel.RelNode, int)

getExpressionLineage

public @Nullable Set<RexNode> getExpressionLineage(RelNode rel,
 RexNode expression)

Determines the origin of a column.

getTableReferences

public @Nullable Set<RexTableInputRef.RelTableRef> getTableReferences(RelNode rel)

Determines the tables used by a plan.

getTableOrigin

public @Nullable RelOptTable getTableOrigin(RelNode rel)

Determines the origin of a RelNode, provided it maps to a single table, optionally with filtering and projection.

Parameters:

rel - the RelNode

Returns:

the table, if the RelNode is a simple table; otherwise null

getSelectivity

public @Nullable Double getSelectivity(RelNode rel,
 @Nullable RexNode predicate)

Returns the BuiltInMetadata.Selectivity.getSelectivity(RexNode) statistic.

Parameters:

rel - the relational expression

predicate - predicate whose selectivity is to be estimated against rel's output

Returns:

estimated selectivity (between 0.0 and 1.0), or null if no reliable estimate can be determined

getUniqueKeys

public @Nullable Set<ImmutableBitSet> getUniqueKeys(RelNode rel)

Returns the BuiltInMetadata.UniqueKeys.getUniqueKeys(boolean) statistic.

Parameters:

rel - the relational expression

Returns:

set of keys, or null if this information cannot be determined (whereas empty set indicates definitely no keys at all)

getUniqueKeys

public @Nullable Set<ImmutableBitSet> getUniqueKeys(RelNode rel,
 boolean ignoreNulls)

Returns the BuiltInMetadata.UniqueKeys.getUniqueKeys(boolean) statistic.

Parameters:

rel - the relational expression

ignoreNulls - if true, ignore null values when determining whether the keys are unique

Returns:

set of keys, or null if this information cannot be determined (whereas empty set indicates definitely no keys at all)

areRowsUnique

public @Nullable Boolean areRowsUnique(RelNode rel,
 boolean ignoreNulls)

Returns whether the rows of a given relational expression are distinct, optionally ignoring NULL values.

This is derived by applying the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(org.apache.calcite.util.ImmutableBitSet, boolean) statistic over all columns. If BuiltInMetadata.MaxRowCount.getMaxRowCount() is less than or equal to one, we shortcut the process and declare the rows unique.

Parameters:

rel - the relational expression

ignoreNulls - if true, ignore null values when determining column uniqueness

Returns:

whether the rows are unique, or null if not enough information is available to make that determination

areRowsUnique

public @Nullable Boolean areRowsUnique(RelNode rel)

Returns whether the rows of a given relational expression are distinct.

Derived by calling areRowsUnique(RelNode, boolean).

Parameters:

rel - the relational expression

Returns:

whether the rows are unique, or null if not enough information is available to make that determination

areColumnsUnique

public @Nullable Boolean areColumnsUnique(RelNode rel,
 ImmutableBitSet columns)

Returns the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(ImmutableBitSet, boolean) statistic.

Parameters:

rel - the relational expression

columns - column mask representing the subset of columns for which uniqueness will be determined

Returns:

true or false depending on whether the columns are unique, or null if not enough information is available to make that determination

areColumnsUnique

public @Nullable Boolean areColumnsUnique(RelNode rel,
 ImmutableBitSet columns,
 boolean ignoreNulls)

Returns the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(ImmutableBitSet, boolean) statistic.

Parameters:

rel - the relational expression

columns - column mask representing the subset of columns for which uniqueness will be determined

ignoreNulls - if true, ignore null values when determining column uniqueness

Returns:

true or false depending on whether the columns are unique, or null if not enough information is available to make that determination

collations

public @Nullable com.google.common.collect.ImmutableList<RelCollation> collations(RelNode rel)

Returns the BuiltInMetadata.Collation.collations() statistic.

Parameters:

rel - the relational expression

Returns:

List of sorted column combinations, or null if not enough information is available to make that determination

distribution

public RelDistribution distribution(RelNode rel)

Returns the BuiltInMetadata.Distribution.distribution() statistic.

Parameters:

rel - the relational expression

Returns:

List of sorted column combinations, or null if not enough information is available to make that determination

getPopulationSize

public @Nullable Double getPopulationSize(RelNode rel,
 ImmutableBitSet groupKey)

Returns the BuiltInMetadata.PopulationSize.getPopulationSize(ImmutableBitSet) statistic.

Parameters:

rel - the relational expression

groupKey - column mask representing the subset of columns for which the row count will be determined

Returns:

distinct row count for the given groupKey, or null if no reliable estimate can be determined

getAverageRowSize

public @Nullable Double getAverageRowSize(RelNode rel)

Returns the BuiltInMetadata.Size.averageRowSize() statistic.

Parameters:

rel - the relational expression

Returns:

average size of a row, in bytes, or null if not known

getAverageColumnSizes

public @Nullable List<@Nullable Double> getAverageColumnSizes(RelNode rel)

Returns the BuiltInMetadata.Size.averageColumnSizes() statistic.

Parameters:

rel - the relational expression

Returns:

a list containing, for each column, the average size of a column value, in bytes. Each value or the entire list may be null if the metadata is not available

getAverageColumnSizesNotNull

public List<@Nullable Double> getAverageColumnSizesNotNull(RelNode rel)

As getAverageColumnSizes(org.apache.calcite.rel.RelNode) but never returns a null list, only ever a list of nulls.

isPhaseTransition

public @Nullable Boolean isPhaseTransition(RelNode rel)

Returns the BuiltInMetadata.Parallelism.isPhaseTransition() statistic.

Parameters:

rel - the relational expression

Returns:

whether each physical operator implementing this relational expression belongs to a different process than its inputs, or null if not known

splitCount

public @Nullable Integer splitCount(RelNode rel)

Returns the BuiltInMetadata.Parallelism.splitCount() statistic.

Parameters:

rel - the relational expression

Returns:

the number of distinct splits of the data, or null if not known

memory

public @Nullable Double memory(RelNode rel)

Returns the BuiltInMetadata.Memory.memory() statistic.

Parameters:

rel - the relational expression

Returns:

the expected amount of memory, in bytes, required by a physical operator implementing this relational expression, across all splits, or null if not known

cumulativeMemoryWithinPhase

public @Nullable Double cumulativeMemoryWithinPhase(RelNode rel)

Returns the BuiltInMetadata.Memory.cumulativeMemoryWithinPhase() statistic.

Parameters:

rel - the relational expression

Returns:

the cumulative amount of memory, in bytes, required by the physical operator implementing this relational expression, and all other operators within the same phase, across all splits, or null if not known

cumulativeMemoryWithinPhaseSplit

public @Nullable Double cumulativeMemoryWithinPhaseSplit(RelNode rel)

Returns the BuiltInMetadata.Memory.cumulativeMemoryWithinPhaseSplit() statistic.

Parameters:

rel - the relational expression

Returns:

the expected cumulative amount of memory, in bytes, required by the physical operator implementing this relational expression, and all operators within the same phase, within each split, or null if not known

isMeasure

public @Nullable Boolean isMeasure(RelNode rel,
 int column)

Returns the BuiltInMetadata.Measure.isMeasure(int) statistic.

Parameters:

rel - The relational expression

column - Output column of the relational expression

Returns:

whether column is a measure

expand

public RexNode expand(RelNode rel,
 int column,
 BuiltInMetadata.Measure.Context context)

Returns the BuiltInMetadata.Measure.expand(int, BuiltInMetadata.Measure.Context) statistic.

Parameters:

rel - The relational expression

column - Output column of the relational expression

context - Context of the use of the measure

Returns:

expression for measure in the context

getDistinctRowCount

public @Nullable Double getDistinctRowCount(RelNode rel,
 ImmutableBitSet groupKey,
 @Nullable RexNode predicate)

Returns the BuiltInMetadata.DistinctRowCount.getDistinctRowCount(ImmutableBitSet, RexNode) statistic.

Parameters:

rel - the relational expression

groupKey - column mask representing group by columns

predicate - pre-filtered predicates

Returns:

distinct row count for groupKey, filtered by predicate, or null if no reliable estimate can be determined

getPulledUpPredicates

public RelOptPredicateList getPulledUpPredicates(RelNode rel)

Returns the BuiltInMetadata.Predicates.getPredicates() statistic.

Parameters:

rel - the relational expression

Returns:

Predicates that can be pulled above this RelNode

getAllPredicates

public @Nullable RelOptPredicateList getAllPredicates(RelNode rel)

Returns the BuiltInMetadata.AllPredicates.getAllPredicates() statistic.

Parameters:

rel - the relational expression

Returns:

All predicates within and below this RelNode

isVisibleInExplain

public Boolean isVisibleInExplain(RelNode rel,
 SqlExplainLevel explainLevel)

Returns the BuiltInMetadata.ExplainVisibility.isVisibleInExplain(SqlExplainLevel) statistic.

Parameters:

rel - the relational expression

explainLevel - level of detail

Returns:

true for visible, false for invisible; if no metadata is available, defaults to true

getDistribution

public @Nullable RelDistribution getDistribution(RelNode rel)

Returns the BuiltInMetadata.Distribution.distribution() statistic.

Parameters:

rel - the relational expression

Returns:

description of how the rows in the relational expression are physically distributed

getLowerBoundCost

public @Nullable RelOptCost getLowerBoundCost(RelNode rel,
 VolcanoPlanner planner)

Returns the lower bound cost of a RelNode.