com.hazelcast.org.apache.calcite.rel.PhysicalNode Maven / Gradle / Ivy
/*
* 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 com.hazelcast.com.liance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.com.hazelcast.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 com.hazelcast.org.apache.calcite.rel;
import com.hazelcast.org.apache.calcite.plan.Convention;
import com.hazelcast.org.apache.calcite.plan.DeriveMode;
import com.hazelcast.org.apache.calcite.plan.RelOptRule;
import com.hazelcast.org.apache.calcite.plan.RelTraitSet;
import com.hazelcast.org.apache.calcite.rel.core.Sort;
import com.hazelcast.org.apache.calcite.util.Pair;
import java.util.ArrayList;
import java.util.List;
/**
* Physical node in a planner that is capable of doing
* physical trait propagation and derivation.
*
* How to use?
*
*
* - Enable top-down optimization by setting
* {@link com.hazelcast.org.apache.calcite.plan.volcano.VolcanoPlanner#setTopDownOpt(boolean)}.
*
*
* - Let your convention's rel interface extends {@link PhysicalNode},
* see {@link com.hazelcast.org.apache.calcite.adapter.enumerable.EnumerableRel} as
* an example.
*
* - Each physical operator overrides any one of the two methods:
* {@link PhysicalNode#passThrough(RelTraitSet)} or
* {@link PhysicalNode#passThroughTraits(RelTraitSet)} depending on
* your needs.
*
* - Choose derive mode for each physical operator by overriding
* {@link PhysicalNode#getDeriveMode()}.
*
* - If the derive mode is {@link DeriveMode#OMAKASE}, override
* method {@link PhysicalNode#derive(List)} in the physical operator,
* otherwise, override {@link PhysicalNode#derive(RelTraitSet, int)}
* or {@link PhysicalNode#deriveTraits(RelTraitSet, int)}.
*
* - Mark your enforcer operator by overriding {@link RelNode#isEnforcer()},
* see {@link Sort#isEnforcer()} as an example. This is important,
* because it can help {@code VolcanoPlanner} avoid unnecessary
* trait propagation and derivation, therefore improve optimization
* efficiency.
*
* - Implement {@link Convention#enforce(RelNode, RelTraitSet)}
* in your convention, which generates appropriate physical enforcer.
* See {@link com.hazelcast.org.apache.calcite.adapter.enumerable.EnumerableConvention}
* as example. Simply return {@code null} if you don't want physical
* trait enforcement.
*
*/
public interface PhysicalNode extends RelNode {
/**
* Pass required traitset from parent node to child nodes,
* returns new node after traits is passed down.
*/
default RelNode passThrough(RelTraitSet required) {
Pair> p = passThroughTraits(required);
if (p == null) {
return null;
}
int size = getInputs().size();
assert size == p.right.size();
List list = new ArrayList<>(size);
for (int i = 0; i < size; i++) {
RelNode n = RelOptRule.convert(getInput(i), p.right.get(i));
list.add(n);
}
return copy(p.left, list);
}
/**
* Pass required traitset from parent node to child nodes,
* returns a pair of traits after traits is passed down.
*
* Pair.left: the new traitset
*
Pair.right: the list of required traitsets for child nodes
*/
default Pair> passThroughTraits(
RelTraitSet required) {
throw new RuntimeException(getClass().getName()
+ "#passThroughTraits() is not implemented.");
}
/**
* Derive traitset from child node, returns new node after
* traits derivation.
*/
default RelNode derive(RelTraitSet childTraits, int childId) {
Pair> p = deriveTraits(childTraits, childId);
if (p == null) {
return null;
}
int size = getInputs().size();
assert size == p.right.size();
List list = new ArrayList<>(size);
for (int i = 0; i < size; i++) {
RelNode node = getInput(i);
node = RelOptRule.convert(node, p.right.get(i));
list.add(node);
}
return copy(p.left, list);
}
/**
* Derive traitset from child node, returns a pair of traits after
* traits derivation.
*
* Pair.left: the new traitset
*
Pair.right: the list of required traitsets for child nodes
*/
default Pair> deriveTraits(
RelTraitSet childTraits, int childId) {
throw new RuntimeException(getClass().getName()
+ "#deriveTraits() is not implemented.");
}
/**
* Given a list of child traitsets,
* inputTraits.size() == getInput().size(),
* returns node list after traits derivation. This method is called
* ONLY when the derive mode is OMAKASE.
*/
default List derive(List> inputTraits) {
throw new RuntimeException(getClass().getName()
+ "#derive() is not implemented.");
}
/**
* Returns mode of derivation.
*/
default DeriveMode getDeriveMode() {
return DeriveMode.LEFT_FIRST;
}
}