RelMetadataQuery (Apache Calcite core API)

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 and Description
`protected`	`RelMetadataQuery()` Creates the instance with `JaninoRelMetadataProvider` instance from `RelMetadataQueryBase.THREAD_PROVIDERS` and `EMPTY` as a prototype.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Boolean`	`areColumnsUnique(RelNode rel, ImmutableBitSet columns)` Returns the `BuiltInMetadata.ColumnUniqueness.areColumnsUnique(ImmutableBitSet, boolean)` statistic.
`Boolean`	`areColumnsUnique(RelNode rel, ImmutableBitSet columns, boolean ignoreNulls)` Returns the `BuiltInMetadata.ColumnUniqueness.areColumnsUnique(ImmutableBitSet, boolean)` statistic.
`Boolean`	`areRowsUnique(RelNode rel)` Returns whether the rows of a given relational expression are distinct.
`com.google.common.collect.ImmutableList<RelCollation>`	`collations(RelNode rel)` Returns the `BuiltInMetadata.Collation.collations()` statistic.
`Double`	`cumulativeMemoryWithinPhase(RelNode rel)` Returns the `BuiltInMetadata.Memory.cumulativeMemoryWithinPhase()` statistic.
`Double`	`cumulativeMemoryWithinPhaseSplit(RelNode rel)` Returns the `BuiltInMetadata.Memory.cumulativeMemoryWithinPhaseSplit()` statistic.
`RelDistribution`	`distribution(RelNode rel)` Returns the `BuiltInMetadata.Distribution.distribution()` statistic.
`RelOptPredicateList`	`getAllPredicates(RelNode rel)` Returns the `BuiltInMetadata.AllPredicates.getAllPredicates()` statistic.
`List<Double>`	`getAverageColumnSizes(RelNode rel)` Returns the `BuiltInMetadata.Size.averageColumnSizes()` statistic.
`List<Double>`	`getAverageColumnSizesNotNull(RelNode rel)` As `getAverageColumnSizes(org.apache.calcite.rel.RelNode)` but never returns a null list, only ever a list of nulls.
`Double`	`getAverageRowSize(RelNode rel)` Returns the `BuiltInMetadata.Size.averageRowSize()` statistic.
`RelColumnOrigin`	`getColumnOrigin(RelNode rel, int column)` Determines the origin of a column, provided the column maps to a single column that isn't derived.
`Set<RelColumnOrigin>`	`getColumnOrigins(RelNode rel, int column)` Returns the `BuiltInMetadata.ColumnOrigin.getColumnOrigins(int)` statistic.
`RelOptCost`	`getCumulativeCost(RelNode rel)` Returns the `BuiltInMetadata.CumulativeCost.getCumulativeCost()` statistic.
`Double`	`getDistinctRowCount(RelNode rel, ImmutableBitSet groupKey, RexNode predicate)` Returns the `BuiltInMetadata.DistinctRowCount.getDistinctRowCount(ImmutableBitSet, RexNode)` statistic.
`RelDistribution`	`getDistribution(RelNode rel)` Returns the `BuiltInMetadata.Distribution.distribution()` statistic.
`Set<RexNode>`	`getExpressionLineage(RelNode rel, RexNode expression)` Determines the origin of a column.
`RelOptCost`	`getLowerBoundCost(RelNode rel, VolcanoPlanner planner)` Returns the lower bound cost of a RelNode.
`Double`	`getMaxRowCount(RelNode rel)` Returns the `BuiltInMetadata.MaxRowCount.getMaxRowCount()` statistic.
`Double`	`getMinRowCount(RelNode rel)` Returns the `BuiltInMetadata.MinRowCount.getMinRowCount()` statistic.
`com.google.common.collect.Multimap<Class<? extends RelNode>,RelNode>`	`getNodeTypes(RelNode rel)` Returns the `BuiltInMetadata.NodeTypes.getNodeTypes()` statistic.
`RelOptCost`	`getNonCumulativeCost(RelNode rel)` Returns the `BuiltInMetadata.NonCumulativeCost.getNonCumulativeCost()` statistic.
`Double`	`getPercentageOriginalRows(RelNode rel)` Returns the `BuiltInMetadata.PercentageOriginalRows.getPercentageOriginalRows()` statistic.
`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.
`Double`	`getSelectivity(RelNode rel, RexNode predicate)` Returns the `BuiltInMetadata.Selectivity.getSelectivity(RexNode)` statistic.
`RelOptTable`	`getTableOrigin(RelNode rel)` Determines the origin of a `RelNode`, provided it maps to a single table, optionally with filtering and projection.
`Set<RexTableInputRef.RelTableRef>`	`getTableReferences(RelNode rel)` Determines the tables used by a plan.
`Set<ImmutableBitSet>`	`getUniqueKeys(RelNode rel)` Returns the `BuiltInMetadata.UniqueKeys.getUniqueKeys(boolean)` statistic.
`Set<ImmutableBitSet>`	`getUniqueKeys(RelNode rel, boolean ignoreNulls)` Returns the `BuiltInMetadata.UniqueKeys.getUniqueKeys(boolean)` statistic.
`static RelMetadataQuery`	`instance()` Returns an instance of RelMetadataQuery.
`Boolean`	`isPhaseTransition(RelNode rel)` Returns the `BuiltInMetadata.Parallelism.isPhaseTransition()` statistic.
`boolean`	`isVisibleInExplain(RelNode rel, SqlExplainLevel explainLevel)` Returns the `BuiltInMetadata.ExplainVisibility.isVisibleInExplain(SqlExplainLevel)` statistic.
`Double`	`memory(RelNode rel)` Returns the `BuiltInMetadata.Memory.memory()` statistic.
`Integer`	`splitCount(RelNode rel)` Returns the `BuiltInMetadata.Parallelism.splitCount()` statistic.

Methods inherited from class org.apache.calcite.rel.metadata.RelMetadataQueryBase
clearCache, initialHandler, revise

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - RelMetadataQuery
```
protected RelMetadataQuery()
```
    Creates the instance with JaninoRelMetadataProvider instance from RelMetadataQueryBase.THREAD_PROVIDERS and EMPTY as a prototype.
- Method Detail
  - instance
```
public static RelMetadataQuery instance()
```
    Returns an instance of RelMetadataQuery. It ensures that cycles do not occur while computing metadata.
  - getNodeTypes
```
public 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 Double getMaxRowCount(RelNode rel)
```
    Returns the BuiltInMetadata.MaxRowCount.getMaxRowCount() statistic.
    
    Parameters:
    
    rel - the relational expression
    
    Returns:
    
    max row count
  - getMinRowCount
```
public Double getMinRowCount(RelNode rel)
```
    Returns the BuiltInMetadata.MinRowCount.getMinRowCount() statistic.
    
    Parameters:
    
    rel - the relational expression
    
    Returns:
    
    max row count
  - getCumulativeCost
```
public 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 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 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 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 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)
  - getExpressionLineage
```
public Set<RexNode> getExpressionLineage(RelNode rel,
                                         RexNode expression)
```
    Determines the origin of a column.
  - getTableReferences
```
public Set<RexTableInputRef.RelTableRef> getTableReferences(RelNode rel)
```
    Determines the tables used by a plan.
  - getTableOrigin
```
public 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 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 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 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 Boolean areRowsUnique(RelNode rel)
```
    Returns whether the rows of a given relational expression are distinct. This is derived by applying the BuiltInMetadata.ColumnUniqueness.areColumnsUnique(org.apache.calcite.util.ImmutableBitSet, boolean) statistic over all columns.
    
    Parameters:
    
    rel - the relational expression
    
    Returns:
    
    true or false depending on whether the rows are unique, or null if not enough information is available to make that determination
  - areColumnsUnique
```
public 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 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 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 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 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 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 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 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 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 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 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 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 Double getDistinctRowCount(RelNode rel,
                                  ImmutableBitSet groupKey,
                                  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 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 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 RelOptCost getLowerBoundCost(RelNode rel,
                                    VolcanoPlanner planner)
```
    Returns the lower bound cost of a RelNode.

Class RelMetadataQuery

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Constructor Detail

RelMetadataQuery

Method Detail

instance

getNodeTypes

getRowCount

getMaxRowCount

getMinRowCount

getCumulativeCost

getNonCumulativeCost

getPercentageOriginalRows

getColumnOrigins

getColumnOrigin

getExpressionLineage

getTableReferences

getTableOrigin

getSelectivity

getUniqueKeys

getUniqueKeys

areRowsUnique

areColumnsUnique

areColumnsUnique

collations

distribution

getPopulationSize

getAverageRowSize

getAverageColumnSizes

getAverageColumnSizesNotNull

isPhaseTransition

splitCount

memory

cumulativeMemoryWithinPhase

cumulativeMemoryWithinPhaseSplit

getDistinctRowCount

getPulledUpPredicates

getAllPredicates

isVisibleInExplain

getDistribution

getLowerBoundCost