org.eigenbase.rel.metadata
Class RelMetadataQuery

java.lang.Object
  org.eigenbase.rel.metadata.RelMetadataQuery

Direct Known Subclasses:

FarragoRelMetadataQuery, LoptMetadataQuery

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 Eigenbase. 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 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. If your new metadata query takes parameters, be sure to register them in the constructor via a call to ReflectiveRelMetadataProvider.mapParameterTypes(java.lang.String, java.util.List).
4. Register your provider class in DefaultRelMetadataProvider.
5. 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.

Version:

$Id: //open/dev/farrago/src/org/eigenbase/rel/metadata/RelMetadataQuery.java#15 $

Author:

John V. Sichi

Constructor Summary

RelMetadataQuery()

Method Summary

static Boolean	areColumnsUnique(RelNode rel, BitSet columns) Determines if a specified set of columns from a specified relational expression are unique.
static Boolean	areColumnsUnique(RelNode rel, BitSet columns, boolean ignoreNulls) Determines if a specified set of columns from a specified relational expression are unique, optionally ignoring null values in the columns.
private static boolean	assertNonNegative(Double result)
private static boolean	assertPercentage(Double result)
static Set<RelColumnOrigin>	getColumnOrigins(RelNode rel, int iOutputColumn) For a given output column of an expression, determines all columns of underlying tables which contribute to result values.
static RelOptCost	getCumulativeCost(RelNode rel) Estimates the cost of executing a relational expression, including the cost of its inputs.
static Double	getDistinctRowCount(RelNode rel, BitSet groupKey, RexNode predicate) Estimates the number of rows which would be produced by a GROUP BY on the set of columns indicated by groupKey, where the input to the GROUP BY has been pre-filtered by predicate.
static RelOptCost	getNonCumulativeCost(RelNode rel) Estimates the cost of executing a relational expression, not counting the cost of its inputs.
static Double	getPercentageOriginalRows(RelNode rel) Estimates the percentage of the number of rows actually produced by an expression out of the number of rows it would produce if all single-table filter conditions were removed.
static Double	getPopulationSize(RelNode rel, BitSet groupKey) Estimates the distinct row count in the original source for the given groupKey, ignoring any filtering being applied by the expression.
static Double	getRowCount(RelNode rel) Estimates the number of rows which will be returned by a relational expression.
static Double	getSelectivity(RelNode rel, RexNode predicate) Estimates the percentage of an expression's output rows which satisfy a given predicate.
static RelStatSource	getStatistics(RelNode rel) Returns statistics for a relational expression.
static Set<BitSet>	getUniqueKeys(RelNode rel) Determines the set of unique minimal keys for this expression.
static Set<BitSet>	getUniqueKeys(RelNode rel, boolean ignoreNulls) Determines the set of unique minimal keys for this expression, optionally ignoring nulls in the columns in the expression.
static boolean	isVisibleInExplain(RelNode rel, SqlExplainLevel explainLevel) Determines whether a relational expression should be visible in EXPLAIN PLAN output at a particular level of detail.
private static Double	validateResult(Double result)

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

getStatistics

public static RelStatSource getStatistics(RelNode rel)

Returns statistics for a relational expression. These statistics include features such as row counts, or column distributions. Stats are typically collected by sampling a table. They might also be inferred from a rel's history. Certain rels, such as filters, might generate stats from their inputs.

Parameters:

rel - the relational expression.

Returns:

a statistics object, if statistics are available, or null otherwise

getRowCount

public static Double getRowCount(RelNode rel)

Estimates the number of rows which will be returned by a relational expression. The default implementation for this query asks the rel itself via RelNode.getRows(), but metadata providers can override this with their own cost models.

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)

Estimates the cost of executing a relational expression, including the cost of its inputs. The default implementation for this query adds getNonCumulativeCost(org.eigenbase.rel.RelNode) to the cumulative cost of each input, but metadata providers can override this with their own cost models, e.g. to take into account interactions between expressions.

Parameters:

rel - the relational expression

Returns:

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

getNonCumulativeCost

public static RelOptCost getNonCumulativeCost(RelNode rel)

Estimates the cost of executing a relational expression, not counting the cost of its inputs. (However, the non-cumulative cost is still usually dependent on the row counts of the inputs.) The default implementation for this query asks the rel itself via RelNode.computeSelfCost(org.eigenbase.relopt.RelOptPlanner), but metadata providers can override this with their own cost models.

Parameters:

rel - the relational expression

Returns:

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

getPercentageOriginalRows

public static Double getPercentageOriginalRows(RelNode rel)

Estimates the percentage of the number of rows actually produced by an expression out of the number of rows it would produce if all single-table filter conditions were removed.

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 iOutputColumn)

For a given output column of an expression, determines all columns of underlying tables which contribute to result values. An output column may have more than one origin due to expressions such as UnionRel and ProjectRel. The optimizer may use this information for catalog access (e.g. index availability).

Parameters:

rel - the relational expression

iOutputColumn - 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)

getSelectivity

public static Double getSelectivity(RelNode rel,
                                    RexNode predicate)

Estimates the percentage of an expression's output rows which satisfy a given predicate. Returns null to indicate that no reliable estimate can be produced.

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<BitSet> getUniqueKeys(RelNode rel)

Determines the set of unique minimal keys for this expression. A key is represented as a BitSet, where each bit position represents a 0-based output column ordinal. (Note that RelNode.isDistinct should return true if and only if at least one key is known.)

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<BitSet> getUniqueKeys(RelNode rel,
                                        boolean ignoreNulls)

Determines the set of unique minimal keys for this expression, optionally ignoring nulls in the columns in the expression. A key is represented as a BitSet, where each bit position represents a 0-based output column ordinal. (Note that RelNode.isDistinct should return true if and only if at least one key is known.)

Nulls can be ignored if the relational expression has filtered out null values.

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,
                                       BitSet columns)

Determines if a specified set of columns from a specified relational expression are unique.

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,
                                       BitSet columns,
                                       boolean ignoreNulls)

Determines if a specified set of columns from a specified relational expression are unique, optionally ignoring null values in the columns. Nulls can be ignored if the relational expression has filtered out null values.

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

getPopulationSize

public static Double getPopulationSize(RelNode rel,
                                       BitSet groupKey)

Estimates the distinct row count in the original source for the given groupKey, ignoring any filtering being applied by the expression. Typically, "original source" means base table, but for derived columns, the estimate may come from a non-leaf rel such as a ProjectRel.

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

getDistinctRowCount

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

Estimates the number of rows which would be produced by a GROUP BY on the set of columns indicated by groupKey, where the input to the GROUP BY has been pre-filtered by predicate. This quantity (leaving out predicate) is often referred to as cardinality (as in gender being a "low-cardinality column").

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

isVisibleInExplain

public static boolean isVisibleInExplain(RelNode rel,
                                         SqlExplainLevel explainLevel)

Determines whether a relational expression should be visible in EXPLAIN PLAN output at a particular level of detail.

Parameters:

rel - the relational expression

explainLevel - level of detail

Returns:

true for visible, false for invisible

assertPercentage

private static boolean assertPercentage(Double result)

assertNonNegative

private static boolean assertNonNegative(Double result)

validateResult

private static Double validateResult(Double result)