Github user fhueske commented on a diff in the pull request:
https://github.com/apache/flink/pull/4046#discussion_r120750870
--- Diff: docs/dev/table/sql.md ---
@@ -22,20 +22,22 @@ specific language governing permissions and limitations
under the License.
-->
-SQL queries are specified using the `sql()` method of the
`TableEnvironment`. The method returns the result of the SQL query as a `Table`
which can be converted into a `DataSet` or `DataStream`, used in subsequent
Table API queries, or written to a `TableSink` (see [Writing Tables to External
Sinks](#writing-tables-to-external-sinks)). SQL and Table API queries can
seamlessly mixed and are holistically optimized and translated into a single
DataStream or DataSet program.
+Flink supports specifying DataStream or DataSet programs with SQL queries
using the `sql()` method of the `TableEnvironment`. The method returns the
result of the SQL query as a `Table`. A `Table` can be used in subsequent SQL /
Table API queries, be converted into a `DataSet` or `DataStream`, or written to
a `TableSink` (see [Writing Tables to External
Sinks](common.html#emit-to-a-tablesink)). SQL and Table API queries can
seamlessly mixed and are holistically optimized and translated into a single
program.
-A `Table`, `DataSet`, `DataStream`, or external `TableSource` must be
registered in the `TableEnvironment` in order to be accessible by a SQL query
(see [Registering Tables](#registering-tables)). For convenience
`Table.toString()` will automatically register an unique table name under the
`Table`'s `TableEnvironment` and return the table name. So it allows to call
SQL directly on tables in a string concatenation (see examples below).
+Before using data in a SQL query, the data source(s) must first be
registered in the `TableEnvironment` (see see [Registering
Tables](common.html#register-a-table-in-the-catalog)). Possible data sources
include Tables, DataSets, DataStreams, and external TableSources.
Alternatively, users can also register external catalogs in the
`TableEnvironment` to specify the location of the data sources.
-*Note: Flink's SQL support is not feature complete, yet. Queries that
include unsupported SQL features will cause a `TableException`. The limitations
of SQL on batch and streaming tables are listed in the following sections.*
+For convenience `Table.toString()` will automatically register a unique
table name under the `Table`'s `TableEnvironment` and return the table name.
This allows SQL to be called directly on tables in a string concatenation (see
examples below).
-**TODO: Rework intro. Move some parts below. **
+*Note: Flink's SQL support is not yet feature complete. Queries that
include unsupported SQL features will cause a `TableException`. The limitations
of SQL on batch and streaming tables are listed in the following sections.*
* This will be replaced by the TOC
{:toc}
Specifying a Query
---------------
+Here are a few examples on specifying a DataStream / DataSet program using
SQL:
--- End diff --
I would not mention that SQL queries are translated into DataStream /
DataSet programs. This is useful information for some users and it should be
mentioned in an internals section. I would assume that most users do not care
about this and might be even confused.
What do you think @haohui ?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
