org.apache.calcite.rel.RelNode Maven / Gradle / Ivy
Show all versions of calcite-core Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to you under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.calcite.rel;
import org.apache.calcite.plan.Convention;
import org.apache.calcite.plan.RelOptCost;
import org.apache.calcite.plan.RelOptNode;
import org.apache.calcite.plan.RelOptPlanner;
import org.apache.calcite.plan.RelOptQuery;
import org.apache.calcite.plan.RelOptTable;
import org.apache.calcite.plan.RelTraitSet;
import org.apache.calcite.rel.core.CorrelationId;
import org.apache.calcite.rel.metadata.Metadata;
import org.apache.calcite.rel.metadata.RelMetadataQuery;
import org.apache.calcite.rel.type.RelDataType;
import org.apache.calcite.rex.RexNode;
import org.apache.calcite.rex.RexShuttle;
import org.apache.calcite.util.ImmutableBitSet;
import org.apache.calcite.util.Litmus;
import java.util.List;
import java.util.Set;
/**
* A RelNode is a relational expression.
*
* Relational expressions process data, so their names are typically verbs:
* Sort, Join, Project, Filter, Scan, Sample.
*
*
A relational expression is not a scalar expression; see
* {@link org.apache.calcite.sql.SqlNode} and {@link RexNode}.
*
* If this type of relational expression has some particular planner rules,
* it should implement the public static method
* {@link AbstractRelNode#register}.
*
* When a relational expression comes to be implemented, the system allocates
* a {@link org.apache.calcite.plan.RelImplementor} to manage the process. Every
* implementable relational expression has a {@link RelTraitSet} describing its
* physical attributes. The RelTraitSet always contains a {@link Convention}
* describing how the expression passes data to its consuming
* relational expression, but may contain other traits, including some applied
* externally. Because traits can be applied externally, implementations of
* RelNode should never assume the size or contents of their trait set (beyond
* those traits configured by the RelNode itself).
*
* For each calling-convention, there is a corresponding sub-interface of
* RelNode. For example,
* {@code org.apache.calcite.adapter.enumerable.EnumerableRel}
* has operations to manage the conversion to a graph of
* {@code org.apache.calcite.adapter.enumerable.EnumerableConvention}
* calling-convention, and it interacts with a
* {@code EnumerableRelImplementor}.
*
* A relational expression is only required to implement its
* calling-convention's interface when it is actually implemented, that is,
* converted into a plan/program. This means that relational expressions which
* cannot be implemented, such as converters, are not required to implement
* their convention's interface.
*
* Every relational expression must derive from {@link AbstractRelNode}. (Why
* have the RelNode interface, then? We need a root interface,
* because an interface can only derive from an interface.)
*/
public interface RelNode extends RelOptNode, Cloneable {
//~ Methods ----------------------------------------------------------------
/**
* Returns a list of this relational expression's child expressions.
* (These are scalar expressions, and so do not include the relational
* inputs that are returned by {@link #getInputs}.
*
* The caller should treat the list as unmodifiable; typical
* implementations will return an immutable list. If there are no
* child expressions, returns an empty list, not null.
*
* @deprecated use #accept(org.apache.calcite.rex.RexShuttle)
* @return List of this relational expression's child expressions
* @see #accept(org.apache.calcite.rex.RexShuttle)
*/
@Deprecated // to be removed before 2.0
List getChildExps();
/**
* Return the CallingConvention trait from this RelNode's
* {@link #getTraitSet() trait set}.
*
* @return this RelNode's CallingConvention
*/
Convention getConvention();
/**
* Returns the name of the variable which is to be implicitly set at runtime
* each time a row is returned from the first input of this relational
* expression; or null if there is no variable.
*
* @return Name of correlating variable, or null
*/
String getCorrelVariable();
/**
* Returns whether the same value will not come out twice. Default value is
* false, derived classes should override.
*
* @return Whether the same value will not come out twice
*
* @deprecated Use {@link RelMetadataQuery#areRowsUnique(RelNode)}
*/
@Deprecated // to be removed before 2.0
boolean isDistinct();
/**
* Returns the ith input relational expression.
*
* @param i Ordinal of input
* @return ith input
*/
RelNode getInput(int i);
/**
* Returns the sub-query this relational expression belongs to.
*
* @return Sub-query
*/
@Deprecated // to be removed before 2.0
RelOptQuery getQuery();
/**
* Returns the type of the rows returned by this relational expression.
*/
RelDataType getRowType();
/**
* Returns the type of the rows expected for an input. Defaults to
* {@link #getRowType}.
*
* @param ordinalInParent input's 0-based ordinal with respect to this
* parent rel
* @return expected row type
*/
RelDataType getExpectedInputRowType(int ordinalInParent);
/**
* Returns an array of this relational expression's inputs. If there are no
* inputs, returns an empty list, not {@code null}.
*
* @return Array of this relational expression's inputs
*/
List getInputs();
/**
* Returns an estimate of the number of rows this relational expression will
* return.
*
* NOTE jvs 29-Mar-2006: Don't call this method directly. Instead, use
* {@link RelMetadataQuery#getRowCount}, which gives plugins a chance to
* override the rel's default ideas about row count.
*
* @param mq Metadata query
* @return Estimate of the number of rows this relational expression will
* return
*/
double estimateRowCount(RelMetadataQuery mq);
/**
* @deprecated Call {@link RelMetadataQuery#getRowCount(RelNode)};
* if you wish to override the default row count formula, override the
* {@link #estimateRowCount(RelMetadataQuery)} method.
*/
@Deprecated // to be removed before 2.0
double getRows();
/**
* Returns the names of variables that are set in this relational
* expression but also used and therefore not available to parents of this
* relational expression.
*
*
Note: only {@link org.apache.calcite.rel.core.Correlate} should set
* variables.
*
*
Note: {@link #getVariablesSet()} is equivalent but returns
* {@link CorrelationId} rather than their names. It is preferable except for
* calling old methods that require a set of strings.
*
* @return Names of variables which are set in this relational
* expression
*
* @deprecated Use {@link #getVariablesSet()}
* and {@link CorrelationId#names(Set)}
*/
@Deprecated // to be removed before 2.0
Set getVariablesStopped();
/**
* Returns the variables that are set in this relational
* expression but also used and therefore not available to parents of this
* relational expression.
*
* Note: only {@link org.apache.calcite.rel.core.Correlate} should set
* variables.
*
* @return Names of variables which are set in this relational
* expression
*/
Set getVariablesSet();
/**
* Collects variables known to be used by this expression or its
* descendants. By default, no such information is available and must be
* derived by analyzing sub-expressions, but some optimizer implementations
* may insert special expressions which remember such information.
*
* @param variableSet receives variables used
*/
void collectVariablesUsed(Set variableSet);
/**
* Collects variables set by this expression.
* TODO: is this required?
*
* @param variableSet receives variables known to be set by
*/
void collectVariablesSet(Set variableSet);
/**
* Interacts with the {@link RelVisitor} in a
* {@link org.apache.calcite.util.Glossary#VISITOR_PATTERN visitor pattern} to
* traverse the tree of relational expressions.
*
* @param visitor Visitor that will traverse the tree of relational
* expressions
*/
void childrenAccept(RelVisitor visitor);
/**
* Returns the cost of this plan (not including children). The base
* implementation throws an error; derived classes should override.
*
* NOTE jvs 29-Mar-2006: Don't call this method directly. Instead, use
* {@link RelMetadataQuery#getNonCumulativeCost}, which gives plugins a
* chance to override the rel's default ideas about cost.
*
* @param planner Planner for cost calculation
* @param mq Metadata query
* @return Cost of this plan (not including children)
*/
RelOptCost computeSelfCost(RelOptPlanner planner, RelMetadataQuery mq);
/**
* @deprecated Call {@link RelMetadataQuery#getNonCumulativeCost(RelNode)};
* if you wish to override the default cost formula, override the
* {@link #computeSelfCost(RelOptPlanner, RelMetadataQuery)} method.
*/
@Deprecated // to be removed before 2.0
RelOptCost computeSelfCost(RelOptPlanner planner);
/**
* Returns a metadata interface.
*
* @param Type of metadata being requested
* @param metadataClass Metadata interface
* @param mq Metadata query
*
* @return Metadata object that supplies the desired metadata (never null,
* although if the information is not present the metadata object may
* return null from all methods)
*/
M metadata(Class metadataClass, RelMetadataQuery mq);
/**
* Describes the inputs and attributes of this relational expression.
* Each node should call {@code super.explain}, then call the
* {@link org.apache.calcite.rel.externalize.RelWriterImpl#input(String, RelNode)}
* and
* {@link org.apache.calcite.rel.externalize.RelWriterImpl#item(String, Object)}
* methods for each input and attribute.
*
* @param pw Plan writer
*/
void explain(RelWriter pw);
/**
* Receives notification that this expression is about to be registered. The
* implementation of this method must at least register all child
* expressions.
*
* @param planner Planner that plans this relational node
* @return Relational expression that should be used by the planner
*/
RelNode onRegister(RelOptPlanner planner);
/**
* Computes the digest, assigns it, and returns it. For planner use only.
*
* @return Digest of this relational expression
*/
String recomputeDigest();
/**
* Replaces the ordinalInParentth input. You must
* override this method if you override {@link #getInputs}.
*
* @param ordinalInParent Position of the child input, 0 is the first
* @param p New node that should be put at position {@code ordinalInParent}
*/
void replaceInput(
int ordinalInParent,
RelNode p);
/**
* If this relational expression represents an access to a table, returns
* that table, otherwise returns null.
*
* @return If this relational expression represents an access to a table,
* returns that table, otherwise returns null
*/
RelOptTable getTable();
/**
* Returns the name of this relational expression's class, sans package
* name, for use in explain. For example, for a
* org.apache.calcite.rel.ArrayRel.ArrayReader, this method returns
* "ArrayReader".
*
* @return Name of this relational expression's class, sans package name,
* for use in explain
*/
String getRelTypeName();
/**
* Returns whether this relational expression is valid.
*
* If assertions are enabled, this method is typically called with
* litmus = THROW, as follows:
*
*
* assert rel.isValid(Litmus.THROW)
*
*
* This signals that the method can throw an {@link AssertionError} if it
* is not valid.
*
* @param litmus What to do if invalid
* @param context Context for validity checking
* @return Whether relational expression is valid
* @throws AssertionError if this relational expression is invalid and
* litmus is THROW
*/
boolean isValid(Litmus litmus, Context context);
@Deprecated // to be removed before 2.0
boolean isValid(boolean fail);
/**
* Returns a description of the physical ordering (or orderings) of this
* relational expression. Never null.
*
* @return Description of the physical ordering (or orderings) of this
* relational expression. Never null
*
* @deprecated Use {@link RelMetadataQuery#distribution(RelNode)}
*/
@Deprecated // to be removed before 2.0
List getCollationList();
/**
* Creates a copy of this relational expression, perhaps changing traits and
* inputs.
*
* Sub-classes with other important attributes are encouraged to create
* variants of this method with more parameters.
*
* @param traitSet Trait set
* @param inputs Inputs
* @return Copy of this relational expression, substituting traits and
* inputs
*/
RelNode copy(
RelTraitSet traitSet,
List inputs);
/**
* Registers any special rules specific to this kind of relational
* expression.
*
* The planner calls this method this first time that it sees a
* relational expression of this class. The derived class should call
* {@link org.apache.calcite.plan.RelOptPlanner#addRule} for each rule, and
* then call {@code super.register}.
*
* @param planner Planner to be used to register additional relational
* expressions
*/
void register(RelOptPlanner planner);
/**
* Returns whether the result of this relational expression is uniquely
* identified by this columns with the given ordinals.
*
* For example, if this relational expression is a LogicalTableScan to
* T(A, B, C, D) whose key is (A, B), then isKey([0, 1]) yields true,
* and isKey([0]) and isKey([0, 2]) yields false.
*
* @param columns Ordinals of key columns
* @return Whether the given columns are a key or a superset of a key
*
* @deprecated Use {@link RelMetadataQuery#areColumnsUnique(RelNode, ImmutableBitSet)}
*/
@Deprecated // to be removed before 2.0
boolean isKey(ImmutableBitSet columns);
/**
* Accepts a visit from a shuttle.
*
* @param shuttle Shuttle
* @return A copy of this node incorporating changes made by the shuttle to
* this node's children
*/
RelNode accept(RelShuttle shuttle);
/**
* Accepts a visit from a shuttle. If the shuttle updates expression, then
* a copy of the relation should be created.
*
* @param shuttle Shuttle
* @return A copy of this node incorporating changes made by the shuttle to
* this node's children
*/
RelNode accept(RexShuttle shuttle);
/** Context of a relational expression, for purposes of checking validity. */
interface Context {
Set correlationIds();
}
}
// End RelNode.java