ExecuteStatement - Execute SQL on Hologres via OpenAPI - Hologres

Synchronously executes SQL on a specified Hologres database and returns results.

Operation description

Securely execute SQL on a Hologres instance via OpenAPI.

Prerequisites:

Enable the "Allow SQL execution through OpenAPI" option on the Data Security tab of the instance details page.
The calling RAM account has the hologram:ExecuteStatement permission.

Supports SELECT, DDL, and DML statements. Use $1, $2 placeholders for parameterized queries to prevent SQL injection. Default result limits: 200 rows (max 1,000) and 10 MB. Exceeding either limit truncates the result, indicated by the truncated response field. Query timeout: 30 seconds.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

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. Maximum length: 16,384 characters. Separate multiple statements with semicolons. Only the last statement's result is returned.	select * from test_table limit 10;
parameters	array	No	Bound parameters for parameterized queries, mapped sequentially to `$1`, `$2` placeholders. Supported types: `String`, `Long`, `Double`, `Boolean`, and `null` (SQL `NULL`). Prevents SQL injection and improves prepared statement cache reuse. Applies to all statements in the sql field.
	any	No	The value of a parameter.	test_val
maxRows	integer	No	Maximum rows to return. Default: 200. Maximum: 1,000. If exceeded, the result is truncated, indicated by the `truncated` response field.	300
maxBytes	integer	No	Maximum response size in bytes. Default: 10,485,760 (10 MB). If exceeded, the response is truncated, indicated by the `truncated` field.	1024
queryTimeout	integer	No	Query timeout in seconds. Default: 30. Range: 1–30. Queries exceeding this limit are canceled.	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	Whether the request succeeded.	True
errorCode	string	Error code. Returned only on failure.	InvalidParameterValue
errorMessage	string	Error message. Returned only on failure.	Invalid parameter value (e.g., SQL is empty or too long)
httpStatusCode	string	The HTTP status code.	200
data	object	The execution result of the SQL statement.
success	boolean	Whether the SQL execution succeeded.
errorCode	string	SQL execution error code. Returned only on failure.	InvalidParameterValue
errorMessage	string	SQL execution error message. Returned only on failure.	Invalid parameter value (e.g., SQL is empty or too long)
results	array<object>	A list of execution results. Always contains exactly one result object. Multiple SELECT statements return only the last result.
	array<object>	An object that contains the result of a single SQL statement.
success	boolean	Whether the SQL execution succeeded.	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. Not returned for SELECT statements.	10
truncated	boolean	Whether the result set was truncated. Returns `true` if the returned rows exceed `MaxResults`.
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`, `text`, and `bool`.	int4
nullable	boolean	Whether the column allows null values.
records	array	The query result records. Each row is an array of strings with all values serialized as strings. NULL values are 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": "Invalid parameter value (for example, the SQL statement is empty or too long)",
  "httpStatusCode": "200",
  "data": {
    "success": false,
    "errorCode": "InvalidParameterValue",
    "errorMessage": "Invalid parameter value (for example, the SQL statement is empty or too long)",
    "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	Insufficient RAM user permissions. Grant the AliyunHologresReadOnlyAccess policy.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.