Github user walterddr commented on a diff in the pull request:
https://github.com/apache/flink/pull/5913#discussion_r184860963
--- Diff: docs/dev/table/sqlClient.md ---
@@ -0,0 +1,539 @@
+---
+title: "SQL Client"
+nav-parent_id: tableapi
+nav-pos: 100
+is_beta: true
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+
+Although Flinkâs Table & SQL API allows to declare queries in the SQL
language. A SQL query needs to be embedded within a table program that is
written either in Java or Scala. The table program needs to be packaged with a
build tool before it can be submitted to a cluster. This limits the usage of
Flink to mostly Java/Scala programmers.
+
+The *SQL Client* aims to provide an easy way of writing, debugging, and
submitting table programs to a Flink cluster without a single line of code. The
*SQL Client CLI* allows for retrieving and visualizing real-time results from
the running distributed application on the command line.
+
+<a href="{{ site.baseurl }}/fig/sql_client_demo.gif"><img class="offset"
src="{{ site.baseurl }}/fig/sql_client_demo.gif" alt="Animated demo of the
Flink SQL Client CLI running table programs on a cluster" width="80%" /></a>
+
+**Note:** The SQL Client is in an early developement phase. Even though
the application is not production-ready yet, it can be a quite useful tool for
prototyping and playing around with Flink SQL. In the future, the community
plans to extend its functionality by providing a REST-based [SQL Client
Gateway](sqlClient.html#limitations--future).
+
+* This will be replaced by the TOC
+{:toc}
+
+Getting Started
+---------------
+
+This section describes how to setup and run your first Flink SQL program
from the command-line. The SQL Client is bundled in the regular Flink
distribution and thus runnable out of the box.
+
+The SQL Client requires a running Flink cluster where table programs can
be submitted to. For more information about setting up a Flink cluster see the
[deployment part of this documentation]({{ site.baseurl
}}/ops/deployment/cluster_setup.html). If you simply want to try out the SQL
Client, you can also start a local cluster with one worker using the following
command:
+
+{% highlight bash %}
+./bin/start-cluster.sh
+{% endhighlight %}
+
+### Starting the SQL Client CLI
+
+The SQL Client scripts are also located in the binary directory of Flink.
You can start the CLI by calling:
+
+{% highlight bash %}
+./bin/sql-client.sh embedded
+{% endhighlight %}
+
+This command starts the submission service and CLI embedded in one
application process. By default, the SQL Client will read its configuration
from the environment file located in `./conf/sql-client-defaults.yaml`. See the
[next part](sqlClient.html#environment-files) for more information about the
structure of environment files.
+
+### Running SQL Queries
+
+Once the CLI has been started, you can use the `HELP` command to list all
available SQL statements. For validating your setup and cluster connection, you
can enter your first SQL query and press the `Enter` key to execute it:
+
+{% highlight sql %}
+SELECT 'Hello World'
+{% endhighlight %}
+
+This query requires no table source and produces a single row result. The
CLI will retrieve results from the cluster and visualize them. You can close
the result view by pressing the `Q` key.
+
+The CLI supports **two modes** for maintaining and visualizing results.
+
+The *table mode* materializes results in memory and visualizes them in a
regular, paginated table representation. It can be enabled by executing the
following command in the CLI:
+
+{% highlight text %}
+SET execution.result-mode=table
+{% endhighlight %}
+
+The *changelog mode* does not materialize results and visualizes the
result stream that is produced by a continuous query [LINK] consisting of
insertions (`+`) and retractions (`-`).
+
+{% highlight text %}
+SET execution.result-mode=changelog
+{% endhighlight %}
+
+You can use the following query to see both result modes in action:
+
+{% highlight sql %}
+SELECT name, COUNT(*) AS cnt FROM (VALUES ('Bob'), ('Alice'), ('Greg'),
('Bob')) AS NameTable(name) GROUP BY name
+{% endhighlight %}
+
+This query performs a bounded word count example. The following sections
explain how to read from table sources and configure other table program
properties.
--- End diff --
can we replace "following sections" with the actual link, docs might be
updated later and the "following" statement might no longer be true
---
