[12/50] [abbrv] calcite git commit: Document RelOptPredicateList

[jh...@apache.org]

Document RelOptPredicateList


Project: http://git-wip-us.apache.org/repos/asf/calcite/repo
Commit: http://git-wip-us.apache.org/repos/asf/calcite/commit/970a8ca9
Tree: http://git-wip-us.apache.org/repos/asf/calcite/tree/970a8ca9
Diff: http://git-wip-us.apache.org/repos/asf/calcite/diff/970a8ca9

Branch: refs/heads/branch-release
Commit: 970a8ca9130111d9ed3425e6ef74d9c86f43c54a
Parents: b1fdd12
Author: Julian Hyde <jh...@apache.org>
Authored: Mon Aug 24 14:29:37 2015 -0700
Committer: Julian Hyde <jh...@apache.org>
Committed: Sun Jan 10 00:51:24 2016 -0800

----------------------------------------------------------------------
 .../calcite/plan/RelOptPredicateList.java       | 60 ++++++++++++++++++++
 1 file changed, 60 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/calcite/blob/970a8ca9/core/src/main/java/org/apache/calcite/plan/RelOptPredicateList.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/plan/RelOptPredicateList.java b/core/src/main/java/org/apache/calcite/plan/RelOptPredicateList.java
index 658ae7f..1dce56d 100644
--- a/core/src/main/java/org/apache/calcite/plan/RelOptPredicateList.java
+++ b/core/src/main/java/org/apache/calcite/plan/RelOptPredicateList.java
@@ -24,14 +24,57 @@ import com.google.common.collect.ImmutableList;
 /**
  * Predicates that are known to hold in the output of a particular relational
  * expression.
+ *
+ * <p><b>Pulled up predicates</b> (field {@link #pulledUpPredicates} are
+ * predicates that apply to every row output by the relational expression. They
+ * are inferred from the input relational expression(s) and the relational
+ * operator.
+ *
+ * <p>For example, if you apply {@code Filter(x > 1)} to a relational
+ * expression that has a predicate {@code y < 10} then the pulled up predicates
+ * for the Filter are {@code [y < 10, x > ]}.
+ *
+ * <p><b>Inferred predicates</b> only apply to joins. If there there is a
+ * predicate on the left input to a join, and that predicate is over columns
+ * used in the join condition, then a predicate can be inferred on the right
+ * input to the join. (And vice versa.)
+ *
+ * <p>For example, in the query
+ * <blockquote>SELECT *<br>
+ * FROM emp<br>
+ * JOIN dept ON emp.deptno = dept.deptno
+ * WHERE emp.gender = 'F' AND emp.deptno &lt; 10</blockquote>
+ * we have
+ * <ul>
+ *   <li>left: {@code Filter(Scan(EMP), deptno < 10},
+ *       predicates: {@code [deptno < 10]}
+ *   <li>right: {@code Scan(DEPT)}, predicates: {@code []}
+ *   <li>join: {@code Join(left, right, emp.deptno = dept.deptno},
+ *      leftInferredPredicates: [],
+ *      rightInferredPredicates: [deptno &lt; 10],
+ *      pulledUpPredicates: [emp.gender = 'F', emp.deptno &lt; 10,
+ *      emp.deptno = dept.deptno, dept.deptno &lt; 10]
+ * </ul>
+ *
+ * <p>Note that the predicate from the left input appears in
+ * {@code rightInferredPredicates}. Predicates from several sources appear in
+ * {@code pulledUpPredicates}.
  */
 public class RelOptPredicateList {
   private static final ImmutableList<RexNode> EMPTY_LIST = ImmutableList.of();
   public static final RelOptPredicateList EMPTY =
       new RelOptPredicateList(EMPTY_LIST, EMPTY_LIST, EMPTY_LIST);
 
+  /** Predicates that can be pulled up from the relational expression and its
+   * inputs. */
   public final ImmutableList<RexNode> pulledUpPredicates;
+
+  /** Predicates that were inferred from the right input.
+   * Empty if the relational expression is not a join. */
   public final ImmutableList<RexNode> leftInferredPredicates;
+
+  /** Predicates that were inferred from the left input.
+   * Empty if the relational expression is not a join. */
   public final ImmutableList<RexNode> rightInferredPredicates;
 
   private RelOptPredicateList(Iterable<RexNode> pulledUpPredicates,
@@ -43,6 +86,14 @@ public class RelOptPredicateList {
         ImmutableList.copyOf(rightInferredPredicates);
   }
 
+  /** Creates a RelOptPredicateList with only pulled-up predicates, no inferred
+   * predicates.
+   *
+   * <p>Use this for relational expressions other than joins.
+   *
+   * @param pulledUpPredicates Predicates that apply to the rows returned by the
+   * relational expression
+   */
   public static RelOptPredicateList of(Iterable<RexNode> pulledUpPredicates) {
     ImmutableList<RexNode> pulledUpPredicatesList =
         ImmutableList.copyOf(pulledUpPredicates);
@@ -53,6 +104,15 @@ public class RelOptPredicateList {
         EMPTY_LIST);
   }
 
+  /** Creates a RelOptPredicateList for a join.
+   *
+   * @param pulledUpPredicates Predicates that apply to the rows returned by the
+   * relational expression
+   * @param leftInferredPredicates Predicates that were inferred from the right
+   *                               input
+   * @param rightInferredPredicates Predicates that were inferred from the left
+   *                                input
+   */
   public static RelOptPredicateList of(Iterable<RexNode> pulledUpPredicates,
       Iterable<RexNode> leftInferredPredicates,
       Iterable<RexNode> rightInferredPredicates) {