SQL: Reflow package-info.java (elastic/x-pack-elasticsearch#3448)
Reflows all the text so it wraps around 75 columns for pleasing reading. And fixes checkstyle errors for the lines that wrap after 140! Original commit: elastic/x-pack-elasticsearch@9630c8c32e
This commit is contained in:
Nik Everett
GitHub
parent
45d2446ce7
commit
27ee786cb6
|
|
@ -29,7 +29,6 @@
|
||||||
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]expression[/\\]function[/\\]scalar[/\\]arithmetic[/\\]Neg.java" checks="LineLength" />
|
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]expression[/\\]function[/\\]scalar[/\\]arithmetic[/\\]Neg.java" checks="LineLength" />
|
||||||
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]expression[/\\]function[/\\]scalar[/\\]datetime[/\\]DateTimeFunction.java" checks="LineLength" />
|
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]expression[/\\]function[/\\]scalar[/\\]datetime[/\\]DateTimeFunction.java" checks="LineLength" />
|
||||||
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]optimizer[/\\]Optimizer.java" checks="LineLength" />
|
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]optimizer[/\\]Optimizer.java" checks="LineLength" />
|
||||||
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]package-info.java" checks="LineLength" />
|
|
||||||
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]parser[/\\]CommandBuilder.java" checks="LineLength" />
|
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]parser[/\\]CommandBuilder.java" checks="LineLength" />
|
||||||
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]parser[/\\]ExpressionBuilder.java" checks="LineLength" />
|
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]parser[/\\]ExpressionBuilder.java" checks="LineLength" />
|
||||||
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]parser[/\\]LogicalPlanBuilder.java" checks="LineLength" />
|
<suppress files="sql[/\\]server[/\\]src[/\\]main[/\\]java[/\\]org[/\\]elasticsearch[/\\]xpack[/\\]sql[/\\]parser[/\\]LogicalPlanBuilder.java" checks="LineLength" />
|
||||||
|
|
|
||||||
|
|
@ -6,140 +6,178 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* <b>X-Pack SQL</b> module is a SQL interface to Elasticsearch. <br>
|
* <b>X-Pack SQL</b> module is a SQL interface to Elasticsearch. <br>
|
||||||
* In a nutshell, currently, SQL acts as a <i>translator</i>, allowing traditional SQL queries to be executed against
|
* In a nutshell, currently, SQL acts as a <i>translator</i>, allowing
|
||||||
* Elasticsearch indices without any modifications. Do note that SQL does <i>not</i> try to hide Elasticsearch or
|
* traditional SQL queries to be executed against Elasticsearch indices
|
||||||
* abstract it in anyway; rather it maps the given SQL, if possible, to one (at the moment) query DSL. Of course,
|
* without any modifications. Do note that SQL does <i>not</i> try to hide
|
||||||
* this means not all SQL queries are supported.<br>
|
* Elasticsearch or abstract it in anyway; rather it maps the given SQL,
|
||||||
*
|
* if possible, to one (at the moment) query DSL. Of course, this means
|
||||||
|
* not all SQL queries are supported.<br>
|
||||||
*
|
*
|
||||||
* <h3>Premise</h3>
|
* <h3>Premise</h3>
|
||||||
* Since Elasticsearch is not a database nor does it supports arbitrary {@code JOIN}s (a cornerstone of SQL),
|
* Since Elasticsearch is not a database nor does it supports arbitrary
|
||||||
* SQL module is built from the ground-up with Elasticsearch in mind first and SQL second.
|
* {@code JOIN}s (a cornerstone of SQL), SQL module is built from the
|
||||||
* In fact, even the grammar introduces Elasticsearch specific components that have no concept in ANSI SQL.
|
* ground-up with Elasticsearch in mind first and SQL second. In fact,
|
||||||
|
* even the grammar introduces Elasticsearch specific components that
|
||||||
|
* have no concept in ANSI SQL.
|
||||||
*
|
*
|
||||||
* <h3>Architecture</h3>
|
* <h3>Architecture</h3>
|
||||||
* SQL module is roughly based on the Volcano project (by Graefe {@code &} co)
|
* SQL module is roughly based on the Volcano project (by Graefe
|
||||||
|
* {@code &} co)
|
||||||
* <a href="http://ieeexplore.ieee.org/document/344061">[1]</a>
|
* <a href="http://ieeexplore.ieee.org/document/344061">[1]</a>
|
||||||
* <a href="https://dl.acm.org/citation.cfm?id=627558">[2]</a>
|
* <a href="https://dl.acm.org/citation.cfm?id=627558">[2]</a>
|
||||||
* <a href="https://scholar.google.com/citations?user=pdDeRScAAAAJ">[3]</a>
|
* <a href="https://scholar.google.com/citations?user=pdDeRScAAAAJ">[3]</a>
|
||||||
*
|
*
|
||||||
* which argues for several design principles, from which 2 are relevant to this project, namely:
|
* which argues for several design principles, from which 2 are relevant
|
||||||
|
* to this project, namely:
|
||||||
*
|
*
|
||||||
* <dl>
|
* <dl>
|
||||||
* <dt>Logical and Physical algebra</dt>
|
* <dt>Logical and Physical algebra</dt>
|
||||||
* <dd>Use of extensible algebraic and logical set of operators to describe the operation to underlying engine.
|
* <dd>Use of extensible algebraic and logical set of operators to
|
||||||
* The engine job is to map a user query into logical algebra and then translate this into physical algebra.</dd>
|
* describe the operation to underlying engine. The engine job is to
|
||||||
|
* map a user query into logical algebra and then translate this into
|
||||||
|
* physical algebra.</dd>
|
||||||
* <dt>Rules to identify patterns</dt>
|
* <dt>Rules to identify patterns</dt>
|
||||||
* <dd>The use of <i>rules</i> as a way to identify relevant <i>pattern</i>s inside the plans that can be worked upon</dd>
|
* <dd>The use of <i>rules</i> as a way to identify relevant
|
||||||
|
* <i>pattern</i>s inside the plans that can be worked upon</dd>
|
||||||
* </dl>
|
* </dl>
|
||||||
*
|
*
|
||||||
* In other words, the use of a logical plan, which represents what the user has requested and a physical plan which is
|
* In other words, the use of a logical plan, which represents what the
|
||||||
* what the engine needs to execute based on the user request.
|
* user has requested and a physical plan which is what the engine needs
|
||||||
* To manipulate the plans, the engine does pattern matching implemented as rules that get applied over and over until
|
* to execute based on the user request. To manipulate the plans, the
|
||||||
* none matches.
|
* engine does pattern matching implemented as rules that get applied over
|
||||||
* An example of a rule would be expanding {@code *} to actual concrete references.
|
* and over until none matches.
|
||||||
|
* An example of a rule would be expanding {@code *} to actual concrete
|
||||||
|
* references.
|
||||||
*
|
*
|
||||||
* As a side-note, the Volcano model has proved quite popular being used (to different degrees) by the majority of SQL
|
* As a side-note, the Volcano model has proved quite popular being used
|
||||||
* engines out there such as Apache Calcite, Apache Impala, Apache Spark and Facebook Presto.
|
* (to different degrees) by the majority of SQL engines out there such
|
||||||
|
* as Apache Calcite, Apache Impala, Apache Spark and Facebook Presto.
|
||||||
*
|
*
|
||||||
* <h3>Concepts</h3>
|
* <h3>Concepts</h3>
|
||||||
*
|
*
|
||||||
* The building operation of the SQL engine is defined by an action, namely a rule (defined in
|
* The building operation of the SQL engine is defined by an action,
|
||||||
* {@link org.elasticsearch.xpack.sql.rule rule} package that accepts one
|
* namely a rule (defined in {@link org.elasticsearch.xpack.sql.rule rule}
|
||||||
* <i>immutable</i> tree (defined in {@link org.elasticsearch.xpack.sql.tree tree} package) and transforms it to another <i>immutable</i>
|
* package that accepts one <i>immutable</i> tree (defined in
|
||||||
* tree.
|
* {@link org.elasticsearch.xpack.sql.tree tree} package) and transforms
|
||||||
* Each rules looks for a certain <i>pattern</i> that it can identify and then transform.
|
* it to another <i>immutable</i> tree.
|
||||||
|
* Each rules looks for a certain <i>pattern</i> that it can identify and
|
||||||
|
* then transform.
|
||||||
*
|
*
|
||||||
* The engine works with 3 main type of trees:
|
* The engine works with 3 main type of trees:
|
||||||
*
|
*
|
||||||
* <dl>
|
* <dl>
|
||||||
* <dt>Logical plan</dt>
|
* <dt>Logical plan</dt>
|
||||||
* <dd><i>Logical</i> representation of a user query. Any transformation of this plan should result in an
|
* <dd><i>Logical</i> representation of a user query. Any transformation
|
||||||
* <i>equivalent</i> plan - meaning for the same input,
|
* of this plan should result in an <i>equivalent</i> plan - meaning for
|
||||||
* it will generate the same output.</dd>
|
* the same input, it will generate the same output.</dd>
|
||||||
* <dt>Physical plan</dt>
|
* <dt>Physical plan</dt>
|
||||||
* <dd><i>Execution</i> representation of a user query. This plan needs to translate to (currently) one query to
|
* <dd><i>Execution</i> representation of a user query. This plan needs
|
||||||
* Elasticsearch. It is likely in the future (once
|
* to translate to (currently) one query to Elasticsearch. It is likely
|
||||||
* we look into supporting {@code JOIN}s, different strategies for generating a physical plan will be available
|
* in the future (once we look into supporting {@code JOIN}s, different
|
||||||
* depending on the cost. </dd>
|
* strategies for generating a physical plan will be available depending
|
||||||
|
* on the cost. </dd>
|
||||||
* <dt>Expression tree</dt>
|
* <dt>Expression tree</dt>
|
||||||
* <dd>Both the logical and physical plan contain an expression trees that need to be incorporated into the query.
|
* <dd>Both the logical and physical plan contain an expression trees
|
||||||
* For the most part, most of the work inside the engine
|
* that need to be incorporated into the query. For the most part, most
|
||||||
* resolves around expressions.</dd>
|
* of the work inside the engine resolves around expressions.</dd>
|
||||||
* </dl>
|
* </dl>
|
||||||
*
|
*
|
||||||
* All types of tree inside the engine have the following properties:
|
* All types of tree inside the engine have the following properties:
|
||||||
* <dl>
|
* <dl>
|
||||||
* <dt>Immutability</dt>
|
* <dt>Immutability</dt>
|
||||||
* <dd>Each node and its properties are immutable. A change in a property results in a new node which results in a
|
* <dd>Each node and its properties are immutable. A change in a property
|
||||||
* new tree.</dd>
|
* results in a new node which results in a new tree.</dd>
|
||||||
* <dt>Resolution</dt>
|
* <dt>Resolution</dt>
|
||||||
* <dd>Due to the algebraic nature of SQL, each tree has the notion of resolution which indicates whether it has been
|
* <dd>Due to the algebraic nature of SQL, each tree has the notion of
|
||||||
* resolved or not. A node can be resolved only if it
|
* resolution which indicates whether it has been resolved or not. A node
|
||||||
* <b>and</b> its children have all been resolved.</dd>
|
* can be resolved only if it <b>and</b> its children have all been
|
||||||
|
* resolved.</dd>
|
||||||
* <dt>Traversal</dt>
|
* <dt>Traversal</dt>
|
||||||
* <dd>Each tree can be traversed top-to-bottom/pre-order/parents-first or bottom-up/post-order/children-first. The
|
* <dd>Each tree can be traversed top-to-bottom/pre-order/parents-first or
|
||||||
* difference in the traversal depends on the pattern that is being
|
* bottom-up/post-order/children-first. The difference in the traversal
|
||||||
* identified.</dd>
|
* depends on the pattern that is being identified.</dd>
|
||||||
* </dl>
|
* </dl>
|
||||||
*
|
*
|
||||||
* A typical flow inside the engine is the following:
|
* A typical flow inside the engine is the following:
|
||||||
*
|
*
|
||||||
* <ol>
|
* <ol>
|
||||||
* <li>The engine is given a query</li>
|
* <li>The engine is given a query</li>
|
||||||
* <li>The query is parsed and transformed into an <i>unresolved</i> AST or logical plan</li>
|
* <li>The query is parsed and transformed into an <i>unresolved</i> AST or
|
||||||
|
* logical plan</li>
|
||||||
* <li>The logical plan gets analyzed and resolved</li>
|
* <li>The logical plan gets analyzed and resolved</li>
|
||||||
* <li>The logical plan gets optimized</li>
|
* <li>The logical plan gets optimized</li>
|
||||||
* <li>The logical plan gets transformed into a physical plan</li>
|
* <li>The logical plan gets transformed into a physical plan</li>
|
||||||
* <li>The physical plan gets mapped and then folded into an Elasticsearch query</li>
|
* <li>The physical plan gets mapped and then folded into an Elasticsearch
|
||||||
|
* query</li>
|
||||||
* <li>The Elasticsearch query gets executed</li>
|
* <li>The Elasticsearch query gets executed</li>
|
||||||
* </ol>
|
* </ol>
|
||||||
*
|
*
|
||||||
* <h4>Digression - Visitors, pattern matching, {@code instanceof} and Java 10/11/12</h4>
|
* <h4>Digression - Visitors, pattern matching, {@code instanceof} and
|
||||||
|
* Java 10/11/12</h4>
|
||||||
*
|
*
|
||||||
* To implement the above concepts, several choices have been made in the engine (which are not common in the rest of the XPack code base).
|
* To implement the above concepts, several choices have been made in the
|
||||||
* In particular the conventions/signatures of {@link org.elasticsearch.xpack.sql.tree.Node tree}s and usage of {@code instanceof} inside {@link org.elasticsearch.xpack.sql.rule.Rule rule}s).
|
* engine (which are not common in the rest of the XPack code base). In
|
||||||
* Java doesn't provide any utilities for tree abstractions or pattern matching for that matter.
|
* particular the conventions/signatures of
|
||||||
* Typically for tree traversal one would employ the <a href="https://en.wikipedia.org/wiki/Visitor_pattern">Visitor</a>
|
* {@link org.elasticsearch.xpack.sql.tree.Node tree}s and usage of
|
||||||
|
* {@code instanceof} inside
|
||||||
|
* {@link org.elasticsearch.xpack.sql.rule.Rule rule}s).
|
||||||
|
* Java doesn't provide any utilities for tree abstractions or pattern
|
||||||
|
* matching for that matter. Typically for tree traversal one would employ
|
||||||
|
* the <a href="https://en.wikipedia.org/wiki/Visitor_pattern">Visitor</a>
|
||||||
* pattern however that is not a suitable candidate for SQL because:
|
* pattern however that is not a suitable candidate for SQL because:
|
||||||
* <ul>
|
* <ul>
|
||||||
* <li>the visitor granularity is a node and patterns are likely to involve multiple nodes</li>
|
* <li>the visitor granularity is a node and patterns are likely to involve
|
||||||
* <li>transforming a tree and identifying a pattern requires holding a state which means either the tree or the visitor become
|
* multiple nodes</li>
|
||||||
* stateful</li>
|
* <li>transforming a tree and identifying a pattern requires holding a
|
||||||
|
* state which means either the tree or the visitor become stateful</li>
|
||||||
* <li>a node can stop traversal (which is not desired)</li>
|
* <li>a node can stop traversal (which is not desired)</li>
|
||||||
* <li>it's unwieldy - every node type requires a dedicated {@code visit} method</li>
|
* <li>it's unwieldy - every node type requires a dedicated {@code visit}
|
||||||
|
* method</li>
|
||||||
* </ul>
|
* </ul>
|
||||||
*
|
*
|
||||||
* While in Java, there might be hope for <a href="http://cr.openjdk.java.net/~briangoetz/amber/pattern-match.html">the future</a>
|
* While in Java, there might be hope for
|
||||||
* Scala has made it a <a href="https://docs.scala-lang.org/tour/pattern-matching.html">core feature</a>. Its byte-code implementation
|
* <a href="http://cr.openjdk.java.net/~briangoetz/amber/pattern-match.html">the future</a>
|
||||||
* is less pretty as it relies on {@code instanceof} checks.
|
* Scala has made it a
|
||||||
* Which is how many rules are implemented in the SQL engine as well. Where possible though, one can use <i>typed</i> traversal by passing
|
* <a href="https://docs.scala-lang.org/tour/pattern-matching.html">core feature</a>.
|
||||||
* a {@code Class} token to the lambdas (i.e. {@link org.elasticsearch.xpack.sql.tree.Node#transformDown(java.util.function.Function, Class) pre-order transformation}).
|
* Its byte-code implementation is less pretty as it relies on
|
||||||
|
* {@code instanceof} checks. Which is how many rules are implemented in
|
||||||
|
* the SQL engine as well. Where possible though, one can use <i>typed</i>
|
||||||
|
* traversal by passing a {@code Class} token to the lambdas (i.e.
|
||||||
|
* {@link org.elasticsearch.xpack.sql.tree.Node#transformDown(java.util.function.Function, Class)
|
||||||
|
* pre-order transformation}).
|
||||||
*
|
*
|
||||||
* <h3>Components</h3>
|
* <h3>Components</h3>
|
||||||
*
|
*
|
||||||
* The SQL engine is made up of the following components:
|
* The SQL engine is made up of the following components:
|
||||||
* <dl>
|
* <dl>
|
||||||
* <dt>{@link org.elasticsearch.xpack.sql.parser Parser} package</dt>
|
* <dt>{@link org.elasticsearch.xpack.sql.parser Parser} package</dt>
|
||||||
* <dd>Tokenizer and Lexer of the SQL grammar. Translates user query into an AST tree ({@code LogicalPlan}. Makes sure the user query is <b>syntactically</b> valid.</dd>
|
* <dd>Tokenizer and Lexer of the SQL grammar. Translates user query into an
|
||||||
|
* AST tree ({@code LogicalPlan}. Makes sure the user query is <b>syntactically</b>
|
||||||
|
* valid.</dd>
|
||||||
* <dt>{@link org.elasticsearch.xpack.sql.analysis.analyzer.PreAnalyzer PreAnalyzer}</dt>
|
* <dt>{@link org.elasticsearch.xpack.sql.analysis.analyzer.PreAnalyzer PreAnalyzer}</dt>
|
||||||
* <dd>Performs basic inspection of the {@code LogicalPlan} for gathering critical information for the main analysis. This stage is separate from {@code Analysis}
|
* <dd>Performs basic inspection of the {@code LogicalPlan} for gathering critical
|
||||||
|
* information for the main analysis. This stage is separate from {@code Analysis}
|
||||||
* since it performs async/remote calls to the cluster. </dd>
|
* since it performs async/remote calls to the cluster. </dd>
|
||||||
* <dt>{@link org.elasticsearch.xpack.sql.analysis.analyzer.Analyzer Analyzer}</dt>
|
* <dt>{@link org.elasticsearch.xpack.sql.analysis.analyzer.Analyzer Analyzer}</dt>
|
||||||
* <dd>Performs {@code LogicalPlan} analysis, resolution and verification. Makes sure the user query is actually valid and <b>semantically</b> valid.</dd>
|
* <dd>Performs {@code LogicalPlan} analysis, resolution and verification. Makes
|
||||||
|
* sure the user query is actually valid and <b>semantically</b> valid.</dd>
|
||||||
* <dt>{@link org.elasticsearch.xpack.sql.optimizer.Optimizer Optimizer}</dt>
|
* <dt>{@link org.elasticsearch.xpack.sql.optimizer.Optimizer Optimizer}</dt>
|
||||||
* <dd>Transforms the <i>resolved</i> {@code LogicalPlan} into a <i>semantically</i> equivalent tree, meaning for the same input, the same output is produced.</dd>
|
* <dd>Transforms the <i>resolved</i> {@code LogicalPlan} into a <i>semantically</i>
|
||||||
|
* equivalent tree, meaning for the same input, the same output is produced.</dd>
|
||||||
* <dt>{@link org.elasticsearch.xpack.sql.planner.Planner Planner}</dt>
|
* <dt>{@link org.elasticsearch.xpack.sql.planner.Planner Planner}</dt>
|
||||||
* <dd>Performs query planning. The planning is made up of two components:
|
* <dd>Performs query planning. The planning is made up of two components:
|
||||||
* <dl>
|
* <dl>
|
||||||
* <dt>{@code Mapper}</dt>
|
* <dt>{@code Mapper}</dt>
|
||||||
* <dd>Maps the {@code LogicalPlan} to a {@code PhysicalPlan}</dd>
|
* <dd>Maps the {@code LogicalPlan} to a {@code PhysicalPlan}</dd>
|
||||||
* <dt>{@code Folder}</dt>
|
* <dt>{@code Folder}</dt>
|
||||||
* <dd>Folds or rolls-up the {@code PhysicalPlan} into an Elasticsearch {@link org.elasticsearch.xpack.sql.plan.physical.EsQueryExec executable query} </dd>
|
* <dd>Folds or rolls-up the {@code PhysicalPlan} into an Elasticsearch
|
||||||
|
* {@link org.elasticsearch.xpack.sql.plan.physical.EsQueryExec executable query}
|
||||||
|
* </dd>
|
||||||
* </dl>
|
* </dl>
|
||||||
* </dd>
|
* </dd>
|
||||||
* <dt>{@link org.elasticsearch.xpack.sql.execution Execution}</dt>
|
* <dt>{@link org.elasticsearch.xpack.sql.execution Execution}</dt>
|
||||||
* <dd>Actual execution of the query, results retrieval, extractions and translation into a {@link org.elasticsearch.xpack.sql.session.RowSet tabular} format.</dd>
|
* <dd>Actual execution of the query, results retrieval, extractions and translation
|
||||||
|
* into a {@link org.elasticsearch.xpack.sql.session.RowSet tabular} format.</dd>
|
||||||
* </dl>
|
* </dl>
|
||||||
*/
|
*/
|
||||||
package org.elasticsearch.xpack.sql;
|
package org.elasticsearch.xpack.sql;
|
||||||
Loading…
Reference in New Issue