Executes an SQL statement synchronously on a specified database via OpenAPI and returns the result.
Operation description
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.
Try it now
Test
RAM authorization
Request syntax
POST /api/v1/instances/{instanceId}/executeStatement HTTP/1.1
Path Parameters
|
Parameter |
Type |
Required |
Description |
Example |
| instanceId |
string |
No |
The ID of the instance. |
hgprecn-cn-i7m2ucpyu005 |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| body |
object |
No |
The request body. |
|
| 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., |
|
|
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 |
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 |
Response elements
|
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 |
Indicates whether the SQL statement was executed successfully. |
True |
| sql |
string |
The executed SQL statement. |
select * from test_table limit 10; |
| count |
integer |
The number of rows returned by a SELECT statement. |
25 |
| updateCount |
integer |
The number of rows affected by an INSERT, UPDATE, or DELETE statement. This parameter is not returned for SELECT statements. |
10 |
| truncated |
boolean |
Indicates whether the result set was truncated. The value is |
|
| queryId |
string |
The ID of the query. |
E3F4B2A7-1234-5678-9ABC-DEF012345678 |
| errorMessage |
string |
The error message for the SQL statement. |
ERROR: relation \"non_existent_table\" does not exist\n Position: 15 |
| errorCode |
string |
The error code for the SQL statement. |
SQL_ERROR |
| columnMetadata |
array<object> |
The metadata of columns in the result set. |
|
|
object |
An object that contains the metadata for a single column. |
||
| name |
string |
The name of the column. |
id |
| type |
string |
The data type of the column, such as |
int4 |
| nullable |
boolean |
Indicates whether the column can be null. |
|
| records |
array |
The set of records that are returned by the query. Each row is an array of strings, and all values are serialized as strings. A NULL value is represented as "\N". |
|
|
array |
An array that represents a single row in the result set. |
||
|
string |
A field value, returned as a string. |
["1", "Alice"] |
Examples
Success response
JSON format
{
"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\"]"
]
]
}
]
}
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 403 | NoPermission | RAM user permission is insufficient, please grant AliyunHologresReadOnlyAccess permission. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.