Package org.apache.calcite.rel

Interface RelNode

All Superinterfaces:
Cloneable, RelOptNode
All Known Subinterfaces:
ArrowRel, BindableRel, CassandraRel, Converter, ElasticsearchRel, EnumerableRel, GeodeRel, InnodbRel, InterpretableRel, JdbcRel, MongoRel, PhysicalNode, PigRel, RelStructuredTypeFlattener.SelfFlatteningRel, SparkRel
All Known Implementing Classes:
AbstractConverter, AbstractRelNode, Aggregate, AsofJoin, Bindables.BindableAggregate, Bindables.BindableFilter, Bindables.BindableIntersect, Bindables.BindableJoin, Bindables.BindableMatch, Bindables.BindableMinus, Bindables.BindableProject, Bindables.BindableSort, Bindables.BindableTableScan, Bindables.BindableUnion, Bindables.BindableValues, Bindables.BindableWindow, BiRel, Calc, CassandraFilter, CassandraLimit, CassandraProject, CassandraSort, CassandraTableScan, CassandraToEnumerableConverter, Chi, Collect, ConverterImpl, Correlate, CsvTableScan, CsvTableScan, Delta, DruidQuery, ElasticsearchAggregate, ElasticsearchFilter, ElasticsearchProject, ElasticsearchSort, ElasticsearchTableScan, ElasticsearchToEnumerableConverter, EnumerableAggregate, EnumerableAggregateBase, EnumerableAsofJoin, EnumerableBatchNestedLoopJoin, EnumerableBindable, EnumerableCalc, EnumerableCollect, EnumerableCorrelate, EnumerableFilter, EnumerableHashJoin, EnumerableInterpretable, EnumerableInterpreter, EnumerableIntersect, EnumerableLimit, EnumerableLimitSort, EnumerableMatch, EnumerableMergeJoin, EnumerableMergeUnion, EnumerableMinus, EnumerableNestedLoopJoin, EnumerableProject, EnumerableRepeatUnion, EnumerableSort, EnumerableSortedAggregate, EnumerableTableFunctionScan, EnumerableTableModify, EnumerableTableScan, EnumerableTableSpool, EnumerableToSparkConverter, EnumerableUncollect, EnumerableUnion, EnumerableValues, EnumerableWindow, EquiJoin, EquiJoin, Exchange, Filter, GeodeAggregate, GeodeFilter, GeodeProject, GeodeSort, GeodeTableScan, GeodeToEnumerableConverter, HepRelVertex, InnodbFilter, InnodbProject, InnodbSort, InnodbTableScan, InnodbToEnumerableConverter, InterpretableConverter, Intersect, JdbcRules.JdbcAggregate, JdbcRules.JdbcCalc, JdbcRules.JdbcFilter, JdbcRules.JdbcIntersect, JdbcRules.JdbcJoin, JdbcRules.JdbcMinus, JdbcRules.JdbcProject, JdbcRules.JdbcSort, JdbcRules.JdbcTableModify, JdbcRules.JdbcUnion, JdbcRules.JdbcValues, JdbcTableScan, JdbcToEnumerableConverter, JdbcToSparkConverter, Join, LogicalAggregate, LogicalAsofJoin, LogicalCalc, LogicalChi, LogicalCorrelate, LogicalDelta, LogicalExchange, LogicalFilter, LogicalIntersect, LogicalJoin, LogicalMatch, LogicalMinus, LogicalProject, LogicalRepeatUnion, LogicalSnapshot, LogicalSort, LogicalSortExchange, LogicalTableFunctionScan, LogicalTableModify, LogicalTableScan, LogicalTableSpool, LogicalUnion, LogicalValues, LogicalWindow, Match, Minus, MongoAggregate, MongoFilter, MongoProject, MongoSort, MongoTableScan, MongoToEnumerableConverter, MultiJoin, NoneConverter, PigAggregate, PigFilter, PigJoin, PigProject, PigTableScan, PigToEnumerableConverter, Project, RelSubset, RepeatUnion, Sample, SetOp, SingleRel, Snapshot, Sort, SortExchange, SparkRules.SparkCalc, SparkRules.SparkValues, SparkToEnumerableConverter, SplunkTableScan, Spool, SqlToRelTestBase.CustomCorrelate, StarTable.StarTableScan, TableFunctionScan, TableModify, TableScan, TableSpool, Uncollect, Union, Values, Window
public interface RelNode extends RelOptNode, Cloneable
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 SqlNode and RexNode.

If this type of relational expression has some particular planner rules, it should implement the public static method AbstractRelNode.register(org.apache.calcite.plan.RelOptPlanner).

When a relational expression comes to be implemented, the system allocates a RelImplementor to manage the process. Every implementable relational expression has a RelTraitSet describing its physical attributes. The RelTraitSet always contains a 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, org.apache.calcite.adapter.enumerable.EnumerableRel has operations to manage the conversion to a graph of org.apache.calcite.adapter.enumerable.EnumerableConvention calling-convention, and it interacts with a 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 AbstractRelNode. (Why have the RelNode interface, then? We need a root interface, because an interface can only derive from an interface.)

  • Method Details

    • getConvention

      @Pure @Nullable Convention getConvention()
      Return the CallingConvention trait from this RelNode's trait set.
      Returns:
      this RelNode's CallingConvention

    • getCorrelVariable

      @Nullable String getCorrelVariable()
      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.
      Returns:
      Name of correlating variable, or null

    • getInput

      RelNode getInput(int i)
      Returns the ith input relational expression.
      Parameters:
      i - Ordinal of input
      Returns:
      ith input

    • getRowType

      RelDataType getRowType()
      Returns the type of the rows returned by this relational expression.
      Specified by:
      getRowType in interface RelOptNode

    • getExpectedInputRowType

      RelDataType getExpectedInputRowType(int ordinalInParent)
      Returns the type of the rows expected for an input. Defaults to getRowType().
      Parameters:
      ordinalInParent - input's 0-based ordinal with respect to this parent rel
      Returns:
      expected row type

    • getInputs

      List<RelNode> getInputs()
      Returns an array of this relational expression's inputs. If there are no inputs, returns an empty list, not null.
      Specified by:
      getInputs in interface RelOptNode
      Returns:
      Array of this relational expression's inputs

    • estimateRowCount

      double estimateRowCount(RelMetadataQuery mq)
      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 RelMetadataQuery.getRowCount(org.apache.calcite.rel.RelNode), which gives plugins a chance to override the rel's default ideas about row count.

      Parameters:
      mq - Metadata query
      Returns:
      Estimate of the number of rows this relational expression will return

    • getVariablesSet

      Set<CorrelationId> getVariablesSet()
      Returns the variables that are set in this relational expression but also used and therefore not available to parents of this relational expression.
      Returns:
      Names of variables which are set in this relational expression

    • collectVariablesUsed

      void collectVariablesUsed(Set<CorrelationId> variableSet)
      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.
      Parameters:
      variableSet - receives variables used

    • collectVariablesSet

      void collectVariablesSet(Set<CorrelationId> variableSet)
      Collects variables set by this expression. TODO: is this required?
      Parameters:
      variableSet - receives variables known to be set by

    • childrenAccept

      void childrenAccept(RelVisitor visitor)
      Interacts with the RelVisitor in a visitor pattern to traverse the tree of relational expressions.
      Parameters:
      visitor - Visitor that will traverse the tree of relational expressions

    • computeSelfCost

      @Nullable RelOptCost computeSelfCost(RelOptPlanner planner, RelMetadataQuery mq)
      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 RelMetadataQuery.getNonCumulativeCost(org.apache.calcite.rel.RelNode), which gives plugins a chance to override the rel's default ideas about cost.

      Parameters:
      planner - Planner for cost calculation
      mq - Metadata query
      Returns:
      Cost of this plan (not including children)

    • metadata

      @Deprecated <@Nullable M extends @Nullable Metadata> M metadata(Class<@Nullable M> metadataClass, RelMetadataQuery mq)
      Deprecated.
      Use RelMetadataQuery via RelOptNode.getCluster().
      Returns a metadata interface.
      Type Parameters:
      M - Type of metadata being requested
      Parameters:
      metadataClass - Metadata interface
      mq - Metadata query
      Returns:
      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)

    • explain

      void explain(RelWriter pw)
      Describes the inputs and attributes of this relational expression. Each node should call super.explain, then call the RelWriter.input(String, RelNode) and RelWriter.item(String, Object) methods for each input and attribute.
      Parameters:
      pw - Plan writer

    • explain

      default String explain()
      Returns a relational expression string of this RelNode. The string returned is the same as RelOptUtil.toString(org.apache.calcite.rel.RelNode).

      This method is intended mainly for use while debugging in an IDE, as a convenient shorthand for RelOptUtil.toString(org.apache.calcite.rel.RelNode). We recommend that classes implementing this interface do not override this method.

      Returns:
      Relational expression string of this RelNode

    • onRegister

      RelNode onRegister(RelOptPlanner planner)
      Receives notification that this expression is about to be registered. The implementation of this method must at least register all child expressions.
      Parameters:
      planner - Planner that plans this relational node
      Returns:
      Relational expression that should be used by the planner

    • getDigest

      default String getDigest()
      Returns a digest string of this RelNode.

      Each call creates a new digest string, so don't forget to cache the result if necessary.

      Specified by:
      getDigest in interface RelOptNode
      Returns:
      Digest string of this RelNode
      See Also:

    • getRelDigest

      @API(since="1.24", status=INTERNAL) RelDigest getRelDigest()
      Returns a digest of this RelNode.

      INTERNAL USE ONLY. For use by the planner.

      Returns:
      Digest of this RelNode
      See Also:

    • recomputeDigest

      @API(since="1.24", status=INTERNAL) void recomputeDigest()
      Recomputes the digest.

      INTERNAL USE ONLY. For use by the planner.

      See Also:

    • deepEquals

      @EnsuresNonNullIf(expression="#1", result=true) boolean deepEquals(@Nullable Object obj)
      Deep equality check for RelNode digest.

      By default this method collects digest attributes from explain terms, then compares each attribute pair.

      Returns:
      Whether the 2 RelNodes are equivalent or have the same digest.
      See Also:

    • deepHashCode

      int deepHashCode()
      Compute deep hash code for RelNode digest.
      See Also:

    • replaceInput

      void replaceInput(int ordinalInParent, RelNode p)
      Replaces the ordinalInParentth input. You must override this method if you override getInputs().
      Parameters:
      ordinalInParent - Position of the child input, 0 is the first
      p - New node that should be put at position ordinalInParent

    • getTable

      @Nullable RelOptTable getTable()
      If this relational expression represents an access to a table, returns that table, otherwise returns null.
      Returns:
      If this relational expression represents an access to a table, returns that table, otherwise returns null

    • getRelTypeName

      String getRelTypeName()
      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".
      Returns:
      Name of this relational expression's class, sans package name, for use in explain

    • isValid

      boolean isValid(Litmus litmus, @Nullable RelNode.Context context)
      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 AssertionError if it is not valid.

      Parameters:
      litmus - What to do if invalid
      context - Context for validity checking
      Returns:
      Whether relational expression is valid
      Throws:
      AssertionError - if this relational expression is invalid and litmus is THROW

    • copy

      RelNode copy(RelTraitSet traitSet, List<RelNode> inputs)
      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.

      Parameters:
      traitSet - Trait set
      inputs - Inputs
      Returns:
      Copy of this relational expression, substituting traits and inputs

    • register

      void register(RelOptPlanner planner)
      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 RelOptPlanner.addRule(org.apache.calcite.plan.RelOptRule) for each rule, and then call super.register.

      Parameters:
      planner - Planner to be used to register additional relational expressions

    • isEnforcer

      default boolean isEnforcer()
      Indicates whether it is an enforcer operator, e.g. PhysicalSort, PhysicalHashDistribute, etc. As an enforcer, the operator must be created only when required traitSet is not satisfied by its input.
      Returns:
      Whether it is an enforcer operator

    • accept

      RelNode accept(RelShuttle shuttle)
      Accepts a visit from a shuttle.
      Parameters:
      shuttle - Shuttle
      Returns:
      A copy of this node incorporating changes made by the shuttle to this node's children

    • accept

      RelNode accept(RexShuttle shuttle)
      Accepts a visit from a shuttle. If the shuttle updates expression, then a copy of the relation should be created. This new relation might have a different row-type.
      Parameters:
      shuttle - Shuttle
      Returns:
      A copy of this node incorporating changes made by the shuttle to this node's children

    • fieldIsNullable

      default boolean fieldIsNullable(int i)
      Returns whether a field is nullable.

    • stripped

      default RelNode stripped()
      Returns this node without any wrapper added by the planner.