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.

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。