diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Alias.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Alias.java index 9a44994239e..6f3ea405fbe 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Alias.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Alias.java @@ -15,6 +15,14 @@ import static java.util.Collections.singletonList; import java.util.Collections; import java.util.List; +/** + * An {@code Alias} is a {@code NamedExpression} that gets renamed to something else through the Alias. + * + * For example, in the statement {@code 5 + 2 AS x}, {@code x} is an alias which is points to {@code ADD(5, 2)}. + * + * And in {@code SELECT col AS x} "col" is a named expression that gets renamed to "x" through an alias. + * + */ public class Alias extends NamedExpression { private final Expression child; diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Attribute.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Attribute.java index d1c58546d29..c8f38113bcf 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Attribute.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Attribute.java @@ -18,6 +18,22 @@ import java.util.List; * {@link Expression}s that can be converted into Elasticsearch * sorts, aggregations, or queries. They can also be extracted * from the result of a search. + * + * In the statement {@code SELECT ABS(foo), A, B+C FROM ...} the three named + * expressions (ABS(foo), A, B+C) get converted to attributes and the user can + * only see Attributes. + * + * In the statement {@code SELECT foo FROM TABLE WHERE foo > 10 + 1} 10+1 is an + * expression. It's not named - meaning there's no alias for it (defined by the + * user) and as such there's no attribute - no column to be returned to the user. + * It's an expression used for filtering so it doesn't appear in the result set + * (derived table). "foo" on the other hand is an expression, a named expression + * (it has a name) and also an attribute - it's a column in the result set. + * + * Another example {@code SELECT foo FROM ... WHERE bar > 10 +1} "foo" gets + * converted into an Attribute, bar does not. That's because bar is used for + * filtering alone but it's not part of the projection meaning the user doesn't + * need it in the derived table. */ public abstract class Attribute extends NamedExpression { diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Expression.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Expression.java index f0fe4e928da..846c06feb09 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Expression.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Expression.java @@ -18,6 +18,15 @@ import java.util.Locale; import static java.lang.String.format; +/** + * In a SQL statement, an Expression is whatever a user specifies inside an + * action, so for instance: + * + * {@code SELECT a, b, MAX(c, d) FROM i} + * + * a, b, ABS(c), and i are all Expressions, with ABS(c) being a Function + * (which is a type of expression) with a single child, c. + */ public abstract class Expression extends Node implements Resolvable { public static class TypeResolution { diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/Function.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/Function.java index 4be482e977a..6c6f1a2633a 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/Function.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/Function.java @@ -15,6 +15,10 @@ import org.elasticsearch.xpack.sql.util.StringUtils; import java.util.List; import java.util.StringJoiner; +/** + * Any SQL expression with parentheses, like {@code MAX()}, or {@code ABS()}. A + * function is always a {@code NamedExpression}. + */ public abstract class Function extends NamedExpression { private final String functionName, name; diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/aggregate/AggregateFunction.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/aggregate/AggregateFunction.java index aeadc724707..413ecf96464 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/aggregate/AggregateFunction.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/aggregate/AggregateFunction.java @@ -16,6 +16,9 @@ import java.util.Objects; import static java.util.Collections.emptyList; import static java.util.Collections.singletonList; +/** + * A type of {@code Function} that takes multiple values and extracts a single value out of them. For example, {@code AVG()}. + */ public abstract class AggregateFunction extends Function { private final Expression field; diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/ScalarFunction.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/ScalarFunction.java index 2e6d8153cde..8462ee293cc 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/ScalarFunction.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/ScalarFunction.java @@ -23,6 +23,12 @@ import static java.util.Collections.emptyList; import static org.elasticsearch.xpack.sql.expression.function.scalar.script.ParamsBuilder.paramsBuilder; import static org.elasticsearch.xpack.sql.expression.function.scalar.script.ScriptTemplate.formatTemplate; +/** + * A {@code ScalarFunction} is a {@code Function} that takes values from some + * operation and converts each to another value. An example would be + * {@code ABS()}, which takes one value at a time, applies a function to the + * value (abs) and returns a new value. + */ public abstract class ScalarFunction extends Function { private ScalarFunctionAttribute lazyAttribute = null; diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/definition/ProcessorDefinition.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/definition/ProcessorDefinition.java index 605aae63f4d..929367fca94 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/definition/ProcessorDefinition.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/definition/ProcessorDefinition.java @@ -14,6 +14,14 @@ import org.elasticsearch.xpack.sql.tree.Node; import java.util.List; +/** + * Contains the tree for processing a function, so for example, the {@code ProcessorDefinition} of: + * + * ABS(MAX(foo)) + CAST(bar) + * + * Is an {@code Add} Function with left {@code ABS} over an aggregate (MAX), and + * right being a {@code CAST} function. + */ public abstract class ProcessorDefinition extends Node implements FieldExtraction { private final Expression expression; diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/runtime/Processor.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/runtime/Processor.java index f77568368b4..9fb67fb51a1 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/runtime/Processor.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/runtime/Processor.java @@ -7,6 +7,12 @@ package org.elasticsearch.xpack.sql.expression.function.scalar.processor.runtime import org.elasticsearch.common.io.stream.NamedWriteable; +/** + * For a scalar function, a {@code Processor} is how we convert the value to convert one value to another value. For instance, ABS(foo). + * Aggregate functions are handled by ES but scalars are not. + * + * This is an opaque class, the computed/compiled result gets saved on the client during scrolling. + */ public interface Processor extends NamedWriteable { Object process(Object input); diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/QueryPlan.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/QueryPlan.java index 66181c5dc68..5d748b54a3d 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/QueryPlan.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/QueryPlan.java @@ -19,6 +19,9 @@ import org.elasticsearch.xpack.sql.tree.Location; import org.elasticsearch.xpack.sql.tree.Node; import org.elasticsearch.xpack.sql.type.DataType; +/** + * There are two main types of plans, {@code LogicalPlan} and {@code PhysicalPlan} + */ public abstract class QueryPlan> extends Node { private AttributeSet lazyOutputSet; @@ -119,4 +122,4 @@ public abstract class QueryPlan> extends No } } } -} \ No newline at end of file +} diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Filter.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Filter.java index ce36333d791..3a7dcdd9919 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Filter.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Filter.java @@ -11,6 +11,11 @@ import org.elasticsearch.xpack.sql.expression.Expression; import org.elasticsearch.xpack.sql.tree.Location; import org.elasticsearch.xpack.sql.tree.NodeInfo; +/** + * A {@code Filter} is a type of Plan that performs filtering of results. In + * {@code SELECT x FROM y WHERE z ..} the "WHERE" clause is a Filter. A + * {@code Filter} has a "condition" Expression that does the filtering. + */ public class Filter extends UnaryPlan { private final Expression condition; diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/LogicalPlan.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/LogicalPlan.java index 189204101c3..c5960c113de 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/LogicalPlan.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/LogicalPlan.java @@ -12,6 +12,10 @@ import org.elasticsearch.xpack.sql.tree.Location; import java.util.List; +/** + * A LogicalPlan is what (not the "how") a user told us they want to do. + * For example, a logical plan in English would be: "I want to get from DEN to SFO". + */ public abstract class LogicalPlan extends QueryPlan implements Resolvable { /** @@ -78,4 +82,4 @@ public abstract class LogicalPlan extends QueryPlan implements Reso @Override public abstract boolean equals(Object obj); -} \ No newline at end of file +} diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Project.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Project.java index 7445d72f43f..4e15b2843a5 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Project.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Project.java @@ -16,6 +16,9 @@ import org.elasticsearch.xpack.sql.expression.function.Functions; import org.elasticsearch.xpack.sql.tree.Location; import org.elasticsearch.xpack.sql.tree.NodeInfo; +/** + * A {@code Project} is a {@code Plan} with one child. In {@code SELECT x FROM y}, the "SELECT" statement is a Project. + */ public class Project extends UnaryPlan { private final List projections; diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/UnaryPlan.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/UnaryPlan.java index e65b9befc2c..637e2594e53 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/UnaryPlan.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/UnaryPlan.java @@ -12,6 +12,10 @@ import java.util.Objects; import org.elasticsearch.xpack.sql.expression.Attribute; import org.elasticsearch.xpack.sql.tree.Location; +/** + * A {@code UnaryPlan} is a {@code LogicalPlan} with exactly one child, for example, {@code WHERE x} in a + * SQL statement is an {@code UnaryPlan}. + */ public abstract class UnaryPlan extends LogicalPlan { private final LogicalPlan child; diff --git a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/physical/PhysicalPlan.java b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/physical/PhysicalPlan.java index 802e81ed8b6..749a494c9d8 100644 --- a/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/physical/PhysicalPlan.java +++ b/plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/physical/PhysicalPlan.java @@ -13,6 +13,12 @@ import org.elasticsearch.xpack.sql.session.Rows; import org.elasticsearch.xpack.sql.tree.Location; import org.elasticsearch.xpack.sql.type.Schema; +/** + * A PhysicalPlan is "how" a LogicalPlan (the "what") actually gets translated into one or more queries. + * + * LogicalPlan = I want to get from DEN to SFO + * PhysicalPlan = take Delta, DEN to SJC, then SJC to SFO + */ public abstract class PhysicalPlan extends QueryPlan implements Executable { private Schema lazySchema;