ExecuteStatement - 执行SQL语句 - 实时数仓Hologres

通过OpenAPI在指定数据库上同步执行SQL语句并返回结果。

接口说明

该 API 用于在 Hologres 实例上通过 OpenAPI 安全执行 SQL 语句。

使用前须满足以下条件：

在管控台实例详情页的"数据安全"中开启"允许通过 OpenAPI 执行 SQL"开关
调用方的 RAM 账号已被授予 hologram:ExecuteStatement 权限

支持 SELECT、DDL、DML 等语句，支持参数化查询（$1, $2 占位符）防止 SQL 注入。查询结果默认最多返回 200 行（上限 1000 行）、10 MB，超出部分截断并通过 truncated 字段标识。单次执行超时 30 秒。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

当前API暂无授权信息透出。

请求语法

POST /api/v1/instances/{instanceId}/executeStatement HTTP/1.1

路径参数

名称	类型	必填	描述	示例值
instanceId	string	否	实例 id。	hgprecn-cn-i7m2ucpyu005

请求参数

名称	类型	必填	描述	示例值
body	object	否	请求体。
dbName	string	否	数据库	test_db
sql	string	否	待执行的 SQL 语句，最大长度 16384 字符。支持多条 SQL 以分号分隔，多条时返回最后一条语句的结果。	select * from test_table limit 10;
parameters	array	否	SQL 参数化查询的绑定参数列表，与 SQL 中的 `$1`, `$2`, ... 占位符按顺序对应。支持的值类型包括：`String`、`Long`、`Double`、`Boolean` 和 `null`（表示 `NULL`）。使用参数化查询可有效防止 SQL 注入，并提升预编译语句的缓存复用率。参数列表作用于 `Statements` 中的每条 SQL。
	any	否	参数集内容	test_val
maxRows	integer	否	最大返回行数，默认 200，最大值 1000。超出部分截断并在响应中通过 `Truncated` 字段标识	300
maxBytes	integer	否	单次返回的最大数据量（字节）。默认 10485760（10 MB），超出时截断并标记 truncated=true。	1024
queryTimeout	integer	否	SQL 执行超时时间（秒）。默认 30，最大 30，最小 1。超时后服务端主动取消查询。	5

返回参数

名称	类型	描述	示例值
	object	结果数据
requestId	string	Id of the request	819A7F0F-2951-540F-BD94-6A41ECF0281F
success	string	是否成功	True
errorCode	string	错误码（成功时为空）	InvalidParameterValue
errorMessage	string	错误信息（成功时为空）	参数值不合法（如 SQL 为空、超长等）
httpStatusCode	string	HTTP 状态码	200
data	object	true:允许 OpenAPI SQL 执行调用；false：未允许 OpenAPI SQL 执行调用
success	boolean	是否成功
errorCode	string	错误码（成功时为空）	InvalidParameterValue
errorMessage	string	错误信息（成功时为空）	参数值不合法（如 SQL 为空、超长等）
results	array<object>	执行结果列表，当前固定长度为 1。多条 select 查询的结果只返回最后一条 select。
	array<object>	结果对象
success	boolean	是否成功	True
sql	string	实际执行的 SQL 语句	select * from test_table limit 10;
count	integer	返回的行数	25
updateCount	integer	语句（INSERT/UPDATE/DELETE）影响的行数，SELECT	10
truncated	boolean	结果是否被截断（超过 `MaxResults` 时为 `true`）
queryId	string	Query ID	E3F4B2A7-1234-5678-9ABC-DEF012345678
errorMessage	string	该条 SQL 的错误信息	ERROR: relation \"non_existent_table\" does not exist\n Position: 15
errorCode	string	该条 SQL 的错误码	SQL_ERROR
columnMetadata	array<object>	列元数据
	object
name	string	列名	id
type	string	数据类型（如 `int4`, `text`, `bool` 等）	int4
nullable	boolean	是否可空
records	array	查询结果行集合。每行为一个字符串数组，所有值序列化为 String，NULL 值表示为 "\N"
	array	每一行结果列表
	string	字段值（字符串形式）	["1", "Alice"]

示例

正常返回示例

JSON格式

{
  "requestId": "819A7F0F-2951-540F-BD94-6A41ECF0281F",
  "success": "True",
  "errorCode": "InvalidParameterValue",
  "errorMessage": "参数值不合法（如 SQL 为空、超长等）",
  "httpStatusCode": "200",
  "data": {
    "success": true,
    "errorCode": "InvalidParameterValue",
    "errorMessage": "参数值不合法（如 SQL 为空、超长等）",
    "results": [
      {
        "success": true,
        "sql": "select * from test_table limit 10;",
        "count": 25,
        "updateCount": 10,
        "truncated": true,
        "queryId": "E3F4B2A7-1234-5678-9ABC-DEF012345678",
        "errorMessage": "ERROR: relation \\\"non_existent_table\\\" does not exist\\n  Position: 15",
        "errorCode": "SQL_ERROR",
        "columnMetadata": [
          {
            "name": "id",
            "type": "int4",
            "nullable": true
          }
        ],
        "records": [
          [
            " [\"1\", \"Alice\"]"
          ]
        ]
      }
    ]
  }
}

错误码

HTTP status code	错误码	错误信息	描述
403	NoPermission	RAM user permission is insufficient, please grant AliyunHologresReadOnlyAccess permission.

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。