ExecuteStatement - Hologres - Alibaba Cloud Documentation Center

Mengeksekusi Pernyataan SQL secara sinkron pada database tertentu melalui OpenAPI dan mengembalikan hasilnya.

Deskripsi operasi

Use this API to securely execute SQL statements on a Hologres instance through OpenAPI.

Before using this API, ensure the following prerequisites are met:

The "Allow SQL execution through OpenAPI" option is enabled on the "Data Security" tab of the instance details page in the console.
The calling RAM account must have the hologram:ExecuteStatement permission.

This API supports statements such as SELECT, DDL, and DML. It also supports parameterized queries with $1 and $2 placeholders to prevent SQL injection. By default, query results are limited to 200 rows (configurable up to 1,000) and 10 MB. Result sets that exceed these limits are truncated, and the truncated field in the response indicates if truncation occurred. The timeout for a single execution is 30 seconds.

Coba sekarang

Coba API ini di OpenAPI Explorer tanpa perlu penandatanganan manual. Panggilan yang berhasil akan secara otomatis menghasilkan contoh kode SDK sesuai dengan parameter Anda. Unduh kode tersebut dengan kredensial bawaan yang aman untuk penggunaan lokal.

Test

RAM authorization

Tidak ada otorisasi untuk operasi ini. Jika Anda mengalami masalah saat menjalankan operasi ini, hubungi dukungan teknis.

Sintaks permintaan

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

Path Parameters

Parameter	Type	Required	Description	Example
instanceId	string	No	ID Instans.	hgprecn-cn-i7m2ucpyu005

Parameter permintaan

Parameter	Type	Required	Description	Example
body	object	No	Badan permintaan.
dbName	string	No	The name of the database.	test_db
sql	string	No	The SQL statement to execute. The maximum length is 16,384 characters. You can specify multiple SQL statements separated by semicolons. If multiple statements are provided, the API returns the result of the last statement.	select * from test_table limit 10;
parameters	array	No	An array of bound parameters for a parameterized query. These parameters map sequentially to placeholders (e.g., `$1`, `$2`) in the SQL statement. Supported types include `String`, `Long`, `Double`, `Boolean`, and `null` (for SQL `NULL`). Using parameterized queries helps prevent SQL injection and improves the cache reuse rate for prepared statements. These parameters apply to all SQL statements in the sql field.
	any	No	The value of a parameter.	test_val
maxRows	integer	No	The maximum number of rows to return. Default: 200. Maximum: 1,000. If the result set exceeds this limit, it is truncated, as indicated by the `Truncated` field in the response.	300
maxBytes	integer	No	The maximum size of the response, in bytes. Default: 10,485,760 (10 MB). If the response size exceeds this limit, it is truncated, as indicated by the Truncated field in the response.	1024
queryTimeout	integer	No	The query timeout, in seconds. Default: 30. Maximum: 30. Minimum: 1. If a query exceeds this time limit, the server cancels it.	5

Elemen respons

Element	Type	Description	Example
	object	The result data.
requestId	string	The ID of the request.	819A7F0F-2951-540F-BD94-6A41ECF0281F
success	string	Indicates whether the request was successful.	True
errorCode	string	The error code. This parameter is returned only if the request fails.	InvalidParameterValue
errorMessage	string	The error message. This parameter is returned only if the request fails.	参数值不合法（如 SQL 为空、超长等）
httpStatusCode	string	The HTTP status code.	200
data	object	The execution result of the SQL statement.
success	boolean	Indicates whether the SQL statement was executed successfully.
errorCode	string	The error code for the SQL statement execution. This parameter is returned only if the execution fails.	InvalidParameterValue
errorMessage	string	The error message for the SQL statement execution. This parameter is returned only if the execution fails.	参数值不合法（如 SQL 为空、超长等）
results	array<object>	A list of execution results. This list always contains exactly one result object. If you execute multiple SELECT statements, only the result of the last one is returned.
	array<object>	An object that contains the result of a single SQL statement.
success	boolean		True
sql	string		select * from test_table limit 10;
count	integer		25
updateCount	integer		10
truncated	boolean
queryId	string		E3F4B2A7-1234-5678-9ABC-DEF012345678
errorMessage	string		ERROR: relation \"non_existent_table\" does not exist\n Position: 15
errorCode	string		SQL_ERROR
columnMetadata	array<object>
	object
name	string		id
type	string		int4
nullable	boolean
records	array
	array
	string		["1", "Alice"]

Contoh

Respons sukses

JSONformat

{
  "requestId": "819A7F0F-2951-540F-BD94-6A41ECF0281F",
  "success": "True",
  "errorCode": "InvalidParameterValue",
  "errorMessage": "参数值不合法（如 SQL 为空、超长等）",
  "httpStatusCode": "200",
  "data": {
    "success": false,
    "errorCode": "InvalidParameterValue",
    "errorMessage": "参数值不合法（如 SQL 为空、超长等）",
    "results": [
      {
        "success": true,
        "sql": "select * from test_table limit 10;",
        "count": 25,
        "updateCount": 10,
        "truncated": false,
        "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": false
          }
        ],
        "records": [
          [
            " [\"1\", \"Alice\"]"
          ]
        ]
      }
    ]
  }
}

Kode kesalahan

HTTP status code	Error code	Error message	Description
403	NoPermission	RAM user permission is insufficient, please grant AliyunHologresReadOnlyAccess permission.

Lihat Error Codes untuk daftar lengkap.

Catatan rilis

Lihat Release Notes untuk daftar lengkap.