[
https://issues.apache.org/jira/browse/FLINK-6749?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16041735#comment-16041735
]
ASF GitHub Bot commented on FLINK-6749:
---------------------------------------
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 ?
> Table API / SQL Docs: SQL Page
> ------------------------------
>
> Key: FLINK-6749
> URL: https://issues.apache.org/jira/browse/FLINK-6749
> Project: Flink
> Issue Type: Sub-task
> Components: Documentation, Table API & SQL
> Affects Versions: 1.3.0
> Reporter: Fabian Hueske
> Assignee: Haohui Mai
>
> Update and refine {{./docs/dev/table/sql.md}} in feature branch
> https://github.com/apache/flink/tree/tableDocs
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
