org.apache.calcite.rel.metadata

Class RelMetadataQuery

java.lang.Object

org.apache.calcite.rel.metadata.RelMetadataQuery

public abstract class RelMetadataQuery
extends Object

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, prepending it to the default providers. Then supply that instance to the planner via the appropriate plugin mechanism.

Constructor Summary

Constructors

Constructor and Description
RelMetadataQuery()

Method Summary

Methods

Modifier and Type	Method and Description
static Boolean	areColumnsUnique(RelNode rel, ImmutableBitSet columns) Returns the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(org.apache.calcite.util.ImmutableBitSet, boolean) statistic.
static Boolean	areColumnsUnique(RelNode rel, ImmutableBitSet columns, boolean ignoreNulls) Returns the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(org.apache.calcite.util.ImmutableBitSet, boolean) statistic.
static com.google.common.collect.ImmutableList<RelCollation>	collations(RelNode rel) Returns the BuiltInMetadata.Collation.collations() statistic.
static Double	cumulativeMemoryWithinPhase(RelNode rel) Returns the BuiltInMetadata.Memory.cumulativeMemoryWithinPhase() statistic.
static Double	cumulativeMemoryWithinPhaseSplit(RelNode rel) Returns the BuiltInMetadata.Memory.cumulativeMemoryWithinPhaseSplit() statistic.
static RelDistribution	distribution(RelNode rel) Returns the BuiltInMetadata.Distribution.distribution() statistic.
static List<Double>	getAverageColumnSizes(RelNode rel) Returns the BuiltInMetadata.Size.averageColumnSizes() statistic.
static List<Double>	getAverageColumnSizesNotNull(RelNode rel) As getAverageColumnSizes(org.apache.calcite.rel.RelNode) but never returns a null list, only ever a list of nulls.
static Double	getAverageRowSize(RelNode rel) Returns the BuiltInMetadata.Size.averageRowSize() statistic.
static RelColumnOrigin	getColumnOrigin(RelNode rel, int column) Determines the origin of a column, provided the column maps to a single column that isn't derived.
static Set<RelColumnOrigin>	getColumnOrigins(RelNode rel, int column) Returns the BuiltInMetadata.ColumnOrigin.getColumnOrigins(int) statistic.
static RelOptCost	getCumulativeCost(RelNode rel) Returns the BuiltInMetadata.CumulativeCost.getCumulativeCost() statistic.
static Double	getDistinctRowCount(RelNode rel, ImmutableBitSet groupKey, RexNode predicate) Returns the BuiltInMetadata.DistinctRowCount.getDistinctRowCount(org.apache.calcite.util.ImmutableBitSet, org.apache.calcite.rex.RexNode) statistic.
static RelOptCost	getNonCumulativeCost(RelNode rel) Returns the BuiltInMetadata.NonCumulativeCost.getNonCumulativeCost() statistic.
static Double	getPercentageOriginalRows(RelNode rel) Returns the BuiltInMetadata.PercentageOriginalRows.getPercentageOriginalRows() statistic.
static Double	getPopulationSize(RelNode rel, ImmutableBitSet groupKey) Returns the BuiltInMetadata.PopulationSize.getPopulationSize(org.apache.calcite.util.ImmutableBitSet) statistic.
static RelOptPredicateList	getPulledUpPredicates(RelNode rel) Returns the BuiltInMetadata.Predicates.getPredicates() statistic.
static Double	getRowCount(RelNode rel) Returns the BuiltInMetadata.RowCount.getRowCount() statistic.
static Double	getSelectivity(RelNode rel, RexNode predicate) Returns the BuiltInMetadata.Selectivity.getSelectivity(RexNode) statistic.
static RelOptTable	getTableOrigin(RelNode rel) Determines the origin of a RelNode, provided it maps to a single table, optionally with filtering and projection.
static Set<ImmutableBitSet>	getUniqueKeys(RelNode rel) Returns the BuiltInMetadata.UniqueKeys.getUniqueKeys(boolean) statistic.
static Set<ImmutableBitSet>	getUniqueKeys(RelNode rel, boolean ignoreNulls) Returns the BuiltInMetadata.UniqueKeys.getUniqueKeys(boolean) statistic.
static Boolean	isPhaseTransition(RelNode rel) Returns the BuiltInMetadata.Parallelism.isPhaseTransition() statistic.
static boolean	isVisibleInExplain(RelNode rel, SqlExplainLevel explainLevel) Returns the BuiltInMetadata.ExplainVisibility.isVisibleInExplain(SqlExplainLevel) statistic.
static Double	memory(RelNode rel) Returns the BuiltInMetadata.Memory.memory() statistic.
static Integer	splitCount(RelNode rel) Returns the BuiltInMetadata.Parallelism.splitCount() statistic.

Methods inherited from class java.lang.Object

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

Constructor Detail

RelMetadataQuery

public RelMetadataQuery()

Method Detail

getRowCount

public static 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

getCumulativeCost

public static 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 static 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 static 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 static 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 static RelColumnOrigin getColumnOrigin(RelNode rel,
                              int column)

Determines the origin of a column, provided the column maps to a single column that isn't derived.

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 provided it's a simple column; otherwise, returns null

See Also:

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

getTableOrigin

public static 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 static Double getSelectivity(RelNode rel,
                    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 static 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 static 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)

areColumnsUnique

public static Boolean areColumnsUnique(RelNode rel,
                       ImmutableBitSet columns)

Returns the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(org.apache.calcite.util.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 static Boolean areColumnsUnique(RelNode rel,
                       ImmutableBitSet columns,
                       boolean ignoreNulls)

Returns the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(org.apache.calcite.util.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 static 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 static 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 static Double getPopulationSize(RelNode rel,
                       ImmutableBitSet groupKey)

Returns the BuiltInMetadata.PopulationSize.getPopulationSize(org.apache.calcite.util.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 static 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 static List<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 static List<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 static 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 static 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 static 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 static 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 static 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

getDistinctRowCount

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

Returns the BuiltInMetadata.DistinctRowCount.getDistinctRowCount(org.apache.calcite.util.ImmutableBitSet, org.apache.calcite.rex.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 static RelOptPredicateList getPulledUpPredicates(RelNode rel)

Returns the BuiltInMetadata.Predicates.getPredicates() statistic.

Parameters:

rel - the relational expression

Returns:

Predicates that can be pulled above this RelNode

isVisibleInExplain

public static 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