yuzelin commented on code in PR #20719: URL: https://github.com/apache/flink/pull/20719#discussion_r966793400
########## docs/content/docs/dev/table/sql-gateway/overview.md: ########## @@ -0,0 +1,226 @@ +--- +title: Overview +weight: 1 +type: docs +aliases: +- /dev/table/sql-gateway.html +--- +<!-- +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. +--> + +Introduction +---------------- + +The SQL Gateway is a service that enables multiple clients from the remote to execute SQL in concurrency. It provides +an easy way to submit the Flink Job, look up the metadata, and analyze the data online. + +The SQL Gateway is composed of a pluggable Endpoint and the SqlGatewayService. The SqlGatewayService is a processor that is +reused by the endpoints to handle the requests. The endpoint is an entry point that allows users to connect. Depending on the +type of the endpoints, users can be using different utils to connect. + +{{< img width="80%" src="/fig/sql-gateway-architecture.png" alt="SQL Gateway Architecture" >}} + +Getting Started +--------------- + +This section describes how to setup and run your first Flink SQL program from the command-line. + +The SQL Gateway is bundled in the regular Flink distribution and thus runnable out-of-the-box. It requires only a running Flink cluster where table programs can be executed. For more information about setting up a Flink cluster see the [Cluster & Deployment]({{< ref "docs/deployment/resource-providers/standalone/overview" >}}) part. If you simply want to try out the SQL Client, you can also start a local cluster with one worker using the following command: + +```bash +./bin/start-cluster.sh +``` +### Starting the SQL Gateway + +The SQL Gateway scripts are also located in the binary directory of Flink. Users can start by calling: + +```bash +./bin/sql-gateway.sh start -Dsql-gateway.endpoint.rest.bind-address=localhost +``` Review Comment: Using this command cannot start the sql gateway, and the log shows that a required option 'address' is missing, so I use '-Dsql-gateway.endpoint.rest.address=localhost' and start the gateway successfully. Please checkout. ########## docs/content/docs/dev/table/sql-gateway/overview.md: ########## @@ -0,0 +1,226 @@ +--- +title: Overview +weight: 1 +type: docs +aliases: +- /dev/table/sql-gateway.html +--- +<!-- +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. +--> + +Introduction +---------------- + +The SQL Gateway is a service that enables multiple clients from the remote to execute SQL in concurrency. It provides +an easy way to submit the Flink Job, look up the metadata, and analyze the data online. + +The SQL Gateway is composed of a pluggable Endpoint and the SqlGatewayService. The SqlGatewayService is a processor that is +reused by the endpoints to handle the requests. The endpoint is an entry point that allows users to connect. Depending on the +type of the endpoints, users can be using different utils to connect. + +{{< img width="80%" src="/fig/sql-gateway-architecture.png" alt="SQL Gateway Architecture" >}} + +Getting Started +--------------- + +This section describes how to setup and run your first Flink SQL program from the command-line. + +The SQL Gateway is bundled in the regular Flink distribution and thus runnable out-of-the-box. It requires only a running Flink cluster where table programs can be executed. For more information about setting up a Flink cluster see the [Cluster & Deployment]({{< ref "docs/deployment/resource-providers/standalone/overview" >}}) part. If you simply want to try out the SQL Client, you can also start a local cluster with one worker using the following command: + +```bash +./bin/start-cluster.sh +``` +### Starting the SQL Gateway + +The SQL Gateway scripts are also located in the binary directory of Flink. Users can start by calling: + +```bash +./bin/sql-gateway.sh start -Dsql-gateway.endpoint.rest.bind-address=localhost +``` + +The command starts the SQL Gateway with REST endpoint that listens on the address localhost:8083. You can use the curl command to check +whether the REST endpoint is available. + +```bash +curl http://localhost:8083/v1/info +{"productName":"Apache Flink","version":"1.16-SNAPSHOT"}% +``` Review Comment: I think the style of the command blocks in the doc that puts the output alongside the command will confuse users. At first glance, I thought all contents was one command:  Just to give an example, I think the following style is OK:  ########## docs/content/docs/dev/table/sql-gateway/overview.md: ########## @@ -0,0 +1,226 @@ +--- +title: Overview +weight: 1 +type: docs +aliases: +- /dev/table/sql-gateway.html +--- +<!-- +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. +--> + +Introduction +---------------- + +The SQL Gateway is a service that enables multiple clients from the remote to execute SQL in concurrency. It provides +an easy way to submit the Flink Job, look up the metadata, and analyze the data online. + +The SQL Gateway is composed of a pluggable Endpoint and the SqlGatewayService. The SqlGatewayService is a processor that is Review Comment: 'The SQL Gateway is composed of a pluggable Endpoint and ...' . I think '... is composed of pluggable endpoints ...' is better according to the figure. ########## docs/content/docs/dev/table/sql-gateway/overview.md: ########## @@ -0,0 +1,226 @@ +--- +title: Overview +weight: 1 +type: docs +aliases: +- /dev/table/sql-gateway.html +--- +<!-- +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. +--> + +Introduction +---------------- + +The SQL Gateway is a service that enables multiple clients from the remote to execute SQL in concurrency. It provides +an easy way to submit the Flink Job, look up the metadata, and analyze the data online. + +The SQL Gateway is composed of a pluggable Endpoint and the SqlGatewayService. The SqlGatewayService is a processor that is +reused by the endpoints to handle the requests. The endpoint is an entry point that allows users to connect. Depending on the +type of the endpoints, users can be using different utils to connect. Review Comment: 'users can use ...' . ########## docs/content/docs/dev/table/sql-gateway/rest.md: ########## @@ -0,0 +1,119 @@ +--- +title: REST Endpoint +weight: 2 +type: docs +aliases: +- /dev/table/sql-gateway/rest.html +--- +<!-- +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. +--> + +# REST Endpoint + +The REST endpoint allows user to connect to SQL Gateway with REST API. + +Overview of Query Processing +---------------- + +### Open Session + +When the client connects to the SQL Gateway, the SQL Gateway creates a `Session` as the context to store the users-specified information +during the interactions between the client and SQL Gateway. After the creation of the `Session`, the SQL Gateway server returns an identifier named +`SessionHandle` for later interactions. + +### Submit SQL + +After the registration of the `Session`, the client can submit the SQL to the SQL Gateway server. When submitting the SQL, +the SQL is translated to an `Operation` and an identifier named `OperationHandle` is returned for later fetch results. The Operation has Review Comment: '... for later fetch results.' I think it should be 'for fetching results later.' ########## docs/content/docs/dev/table/sql-gateway/overview.md: ########## @@ -0,0 +1,226 @@ +--- +title: Overview +weight: 1 +type: docs +aliases: +- /dev/table/sql-gateway.html +--- +<!-- +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. +--> + +Introduction +---------------- + +The SQL Gateway is a service that enables multiple clients from the remote to execute SQL in concurrency. It provides +an easy way to submit the Flink Job, look up the metadata, and analyze the data online. + +The SQL Gateway is composed of a pluggable Endpoint and the SqlGatewayService. The SqlGatewayService is a processor that is +reused by the endpoints to handle the requests. The endpoint is an entry point that allows users to connect. Depending on the +type of the endpoints, users can be using different utils to connect. + +{{< img width="80%" src="/fig/sql-gateway-architecture.png" alt="SQL Gateway Architecture" >}} + +Getting Started +--------------- + +This section describes how to setup and run your first Flink SQL program from the command-line. + +The SQL Gateway is bundled in the regular Flink distribution and thus runnable out-of-the-box. It requires only a running Flink cluster where table programs can be executed. For more information about setting up a Flink cluster see the [Cluster & Deployment]({{< ref "docs/deployment/resource-providers/standalone/overview" >}}) part. If you simply want to try out the SQL Client, you can also start a local cluster with one worker using the following command: + +```bash +./bin/start-cluster.sh +``` +### Starting the SQL Gateway + +The SQL Gateway scripts are also located in the binary directory of Flink. Users can start by calling: + +```bash +./bin/sql-gateway.sh start -Dsql-gateway.endpoint.rest.bind-address=localhost +``` + +The command starts the SQL Gateway with REST endpoint that listens on the address localhost:8083. You can use the curl command to check +whether the REST endpoint is available. + +```bash +curl http://localhost:8083/v1/info +{"productName":"Apache Flink","version":"1.16-SNAPSHOT"}% +``` + +### Running SQL Queries + +For validating your setup and cluster connection, you can work with following steps. + +**Step 1: Open a session** + +```bash +curl --request POST http://localhost:8083/v1/sessions + +{"sessionHandle":"f120b289-7241-420d-aac7-aff774ea6f0e"}% +``` + +**Step 2: Execute a query** + +```bash +curl --request POST http://localhost:8083/v1/sessions/f120b289-7241-420d-aac7-aff774ea6f0e/statements/ \ +--data '{"statement": "SELECT 1"}' + +{"operationHandle":"f2780994-2709-4bed-a1e2-5e7f65ae7794"}% +``` + +**Step 3: Fetch results** +```bash +curl --request GET http://localhost:8083/v1/sessions/f120b289-7241-420d-aac7-aff774ea6f0e/operations/778ac309-8ce7-4c14-8cd6-6951fa2f9897/result/0 + +{ + "results": { + "columns": [ + { + "name": "EXPR$0", + "logicalType": { + "type": "INTEGER", + "nullable": false + } + } + ], + "data": [ + { + "kind": "INSERT", + "fields": [ + 1 + ] + } + ] + }, + "resultType": "PAYLOAD", + "nextResultUri": "/v1/sessions/f120b289-7241-420d-aac7-aff774ea6f0e/operations/778ac309-8ce7-4c14-8cd6-6951fa2f9897/result/1" +}% +``` Review Comment: I think it's better to explain how to use the handle in the command. Users may not know that they need to use their own handle in command and just copy it. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@flink.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
