All Products
Search
Document Center

Hologres:ExecuteStatement

Last Updated:Oct 09, 2026

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:

  1. The "Allow SQL execution through OpenAPI" option is enabled on the "Data Security" tab of the instance details page in the console.

  2. 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

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. 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

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 true if the number of returned rows exceeds the value of 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, or bool.

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.