乌鲁木齐市忆学创美文化传播有限公司
User Avatar

网站建设系统天津网站建设

乌鲁木齐市忆学创美文化传播有限公司 2026/09/09 18:57:44

1. REST Endpoint 的核心交互模型

SQL Gateway 的 REST 交互基本就三步：

  1. Open Session
    客户端创建会话，Gateway 返回SessionHandle，后续所有操作都挂在这个会话上下文下（比如你在会话里USE CATALOG、ADD JAR、SET的东西）。 (Apache Nightlies)

  2. Submit SQL -> Operation
    提交 SQL 后，Gateway 把这条 SQL 变成一个Operation，返回OperationHandle。Operation 有生命周期：你可以cancel取消执行，也可以close释放资源。 (Apache Nightlies)

  3. Fetch Results（分页批次）
    用OperationHandle拉取结果。每次会返回一批数据 + schema，可能还会带nextResultUri用于拉下一批；当拉完会返回resultType=EOS且下一批 URI 为空。 (Apache Nightlies)

这套模型的好处是：你可以像管理“远程查询任务”一样管理 SQL（查状态、取消、释放、分页拉取），非常适合平台化封装。

2. REST Endpoint 关键配置：address / bind-address / port / bind-port

REST Endpoint 的网络配置最容易搞混的是“对外地址”和“绑定地址”的区别：

  • sql-gateway.endpoint.rest.address：客户端用来连接 Gateway 的地址（对外地址）
  • sql-gateway.endpoint.rest.bind-address：Gateway 进程实际绑定的本地地址
  • sql-gateway.endpoint.rest.port：客户端连接的端口（默认 8083）
  • sql-gateway.endpoint.rest.bind-port：Gateway 绑定端口（默认 “8083”，可配置成端口列表、范围，或组合） (Apache Nightlies)

为什么建议 bind-port 配范围

当同一台机器上跑多个 SQL Gateway（多实例、灰度、不同租户）时，固定端口很容易冲突。bind-port支持：

  • 列表："50100,50101"
  • 范围："50100-50200"
  • 组合："50100,50110-50120"

官方也明确建议用范围避免冲突。 (Apache Nightlies)

port 和 bind-port 的关系（快速记忆）

优先级逻辑可以理解为：

  • 你配了bind-port：就按bind-port绑定
  • 否则：绑定port（或默认值）
  • bind-address配了就强制绑定到它，否则按 address/默认行为处理 (Apache Nightlies)

3. OpenAPI 版本：v1 到 v4 各自解决什么

REST Endpoint 提供多版本 OpenAPI（默认 v3），不同版本能力不同：

  • v1：允许提交 statements 并执行
  • v2：支持 SQL Client 连接 Gateway
  • v3：支持 Materialized Table 的 refresh 操作
  • v4：支持 Application Mode 部署脚本（deploy script） (Apache Nightlies)

做平台封装时建议：先 GET/api_versions探测可用版本，再选择你需要的协议版本。

4. v4 常用 API 清单与“该用哪个”

下面按“你在平台里最常用的事情”来分组（都属于你贴出来的 v4）：

4.1 探活与版本协商

  • GET /api_versions：返回可用 API 版本
  • GET /info：返回 Gateway/集群元信息

4.2 会话管理（Session）

  • POST /sessions：创建会话（可带 properties 覆盖默认配置）
  • GET /sessions/:session_handle：查看会话配置
  • DELETE /sessions/:session_handle：关闭会话
  • POST /sessions/:session_handle/heartbeat：心跳续期，配合 idle-timeout 保活

4.3 会话内环境配置（DDL / USE / ADD JAR）

  • POST /sessions/:session_handle/configure-session：执行DDL、USE、LOAD/UNLOAD MODULE、ADD JAR等“搭环境”的语句
    典型用途：建表、切 catalog/database、注册函数、加载 connector 依赖。

4.4 执行 SQL（生成 Operation）

  • POST /sessions/:session_handle/statements：执行一条 statement，返回operation_handle

4.5 Operation 生命周期管理

  • GET /sessions/:session_handle/operations/:operation_handle/status：查状态
  • POST /.../cancel：取消执行
  • DELETE /.../close：关闭 operation 释放资源
  • GET /.../result/:token：分页拉取结果（注意 token 和 rowFormat）

4.6 体验增强与脚本部署

  • GET /sessions/:session_handle/complete-statement：SQL 自动补全提示（做 Web SQL IDE 很有用）
  • POST /sessions/:session_handle/scripts：Application Mode 部署脚本（v4 的核心能力之一）

这些接口的语义在官方 REST Endpoint 文档里都有完整描述。 (Apache Nightlies)

5. 拉取结果时 rowFormat 怎么选：JSON vs PLAIN_TEXT

GET .../result/:token有个必填查询参数rowFormat，它决定 RowData 怎么序列化：

  • JSON：按 Table/RowData 的 JSON 映射返回（能保留类型信息、字段结构）
  • PLAIN_TEXT：自动把所有列 cast 成 String（适合快速展示、日志、调试） (Apache Nightlies)

平台化建议：

  • 面向程序消费：优先 JSON
  • 面向人看的控制台：PLAIN_TEXT 体验更好（少处理类型）

6. 一套可直接照抄的 REST 调用流程（含配置会话、执行、分页、收尾）

下面示例用最小闭环演示“创建会话 → 配置环境 → 执行 SQL → 拉结果 → 关闭资源”。

6.1 创建 Session

SESSION=$(curl-s-XPOST http://localhost:8083/v1/sessions|jq-r.sessionHandle)echo$SESSION

6.2 配置会话（可选：USE / ADD JAR / CREATE TABLE 等）

例如创建临时表（黑洞 sink）：

curl-s-XPOST"http://localhost:8083/v1/sessions/${SESSION}/configure-session"-H'Content-Type: application/json'-d'{"statement":"CREATE TEMPORARY TABLE sink(a INT) WITH (''connector''=''blackhole'')"}'

6.3 执行 statement，拿到 OperationHandle

OP=$(curl-s-XPOST"http://localhost:8083/v1/sessions/${SESSION}/statements"-H'Content-Type: application/json'-d'{"statement":"SELECT 1"}'|jq-r.operationHandle)echo$OP

6.4 拉取结果（注意 rowFormat + token）

curl-s"http://localhost:8083/v1/sessions/${SESSION}/operations/${OP}/result/0?rowFormat=JSON"

如果返回里有nextResultUri，继续 GET 它；直到resultType=EOS。

6.5 收尾（强烈建议做）

curl-s-XDELETE"http://localhost:8083/v1/sessions/${SESSION}/operations/${OP}/close"curl-s-XDELETE"http://localhost:8083/v1/sessions/${SESSION}"

原因很简单：Operation/Session 都会占用服务端资源，不 close 就只能靠超时回收，平台一上量很容易把 gateway 拖慢。

7. 生产封装建议：把 Gateway 当“服务”来治理

  • 必须实现 heartbeat：前端 IDE/Web 平台很容易出现“用户停在页面上不动”，没有心跳会被 idle-timeout 回收；有心跳就能按需保活。 (Apache Nightlies)
  • 必须做 cancel + close：取消只是停止执行，close 才是资源释放；两者都要有入口（比如“停止查询”“关闭结果集”）。 (Apache Nightlies)
  • 结果拉取要支持分页续拉：以nextResultUri或 token 驱动续拉，避免一次性拉爆网关或客户端内存。 (Apache Nightlies)
  • 多实例端口用 bind-port 范围：尤其同机多 gateway、容器 hostNetwork、或灰度并行部署时最关键。 (Apache Nightlies)
  • rowFormat 策略固定：平台层统一约定 JSON/PLAIN_TEXT 的使用场景，避免不同客户端返回结构不一致。
版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈，一经查实，立即删除！

电子商务网站建设苏州企业网站建设

本篇文章来和大家分享一个超简单的，实现多设备 Obsidian 笔记同步的方法。目的就是让咱们无论在什么地方，用的是公司电脑、家里电脑还是手机，一有灵感打开

2026/06/30 11:07:53

网站建设流程网站建设空间

结合AI语音合成，Sonic可实现端到端全自动数字人视频生产在短视频内容爆炸式增长的今天，一个现实摆在创作者面前：观众对高质量、人格化表达的需求越来越高&#x

2026/06/30 13:46:37

九江网站建设天津网站建设公司

Linly-Talker：用AI唤醒记忆，为阿尔茨海默症患者构建有温度的数字陪伴在一间安静的客厅里，一位年过八旬的老人望着窗外喃喃自语：“我记得

2026/06/30 13:53:37

深圳营销型网站建设机票网站建设

Qwen3-VL光污染检测：夜间灯光图像亮度分布统计在城市夜幕降临之际，万家灯火点亮街道的同时，也悄然加剧着一种无形的环境问题——光污染。天文爱好者发现星空越

2026/06/30 12:41:32

银川网站建设网站建设图

POCO C++数据库连接池高效实战：深度解析动态连接管理机制【免费下载链接】pocoThe POCO C++ Libraries are powerfu

2026/06/30 13:14:04

招商网站建设徐汇网站建设

随着大数据时代的到来，电商行业正面临着巨大变化。越来越多的消费者逐渐习惯了在线购物，电商市场的规模不断扩大，因此，数据分析变得尤为关键。而电商A

2026/06/30 12:18:30

网站建设多少钱东营网站建设

你是否曾经为了分离音乐中的人声而反复调整参数？是否在嘈杂环境中录制的音频难以修复？现在，借助本地AI技术，这些问题都能轻松解决。OpenVINO

2026/06/30 13:27:36

青岛网站建设涪陵网站建设

还在为网盘下载速度慢而烦恼吗？网盘直链下载助手为您提供完美解决方案。这款免费开源的浏览器插件能够将各大网盘的分享链接转换为真实下载地址，让您无需安装官方客户端即可享受高速下

2026/06/30 11:04:23

龙岗网站建设公司遵义网站建设

计算机视觉新利器：阿里开源万物识别模型GPU优化指南随着多模态大模型的快速发展，通用图像理解能力正成为AI应用的核心竞争力。阿里巴巴近期开源的“万物识别-中文-通用领域”模

2026/06/30 12:03:59

成都网站建设福田网站建设

layui-admin后台管理系统：5步搭建企业级权限管理平台【免费下载链接】layui-admin基于layui2.x的带后台的通用管理系统项目地址: https://gitcode.

2026/06/30 12:24:01