Execute SQL

Execute SQL on a specified data source through the SQL window flow and return the execution decision, rule and permission precheck summary, and result-set preview.

Request URL: /openapi/v1/sql/execute

Request Method: POST

Before calling this API, complete the OpenAPI setup and confirm that the current AccessKey has the required permissions for the target data source.

Supported data sources

This API runs SQL through the SQL Console execution flow and supports the data source types currently supported by SQL Console for relational databases: MySQL (including MySQL series instances), ShardingProxy, SQL Server, PostgreSQL, PolarDB PostgreSQL, PolarDB Oracle, PolarDB-X, Oracle, OceanBase Oracle, OceanBase MySQL, Db2, ClickHouse, Doris, SelectDB, DM (Da Meng), Kingbase for Oracle, Kingbase for PostgreSQL, Klustron, StarRocks, SingleStore, DWS, MaxCompute, AWS Redshift, openGauss, GaussDB, TiDB, GreatSQL, GaiaDB, GaiaDB-X, Greenplum, Lindorm, Vastbase, GoldenDB, MariaDB, HANA, YashanDB, and YashanDB MySQL.

The data source types available to a specific API caller also depend on the capabilities enabled in the target NineData environment and the current AccessKey permissions. Call GET /openapi/v1/datasource/list first to query the data sources accessible to the current credentials, and use the returned datasourceType to identify the target type. Database groups are not supported by this API.

databaseName and schemaName are optional at the API level, but the connection model of the target data source determines whether these fields are required. OpenAPI does not populate these values from datasourceId: pass databaseName when the data source uses a database level, and pass schemaName when it uses a schema level. Do not pass a field when the data source does not use the corresponding level. The request fails validation when a field required by the target data source is missing.

When the target data source does not use a database or schema level, omit the corresponding field instead of passing an empty string ("") or null. An empty value does not provide a valid database or schema context; for data sources that require that level, leaving the value empty may cause request validation or SQL execution to fail.

Request parameters

Parameter	Type	Required	Description	Example
datasourceId	String	Yes	Data source ID. Database groups are not supported.	ds-dkl5x56dhbv6
databaseName	String	No	Database name. Pass it when the target data source uses a database level; otherwise, omit it.	Not passed
schemaName	String	No	Schema name. Pass it when the target data source uses a schema level; otherwise, omit it.	Not passed
sql	String	Yes	SQL text to execute.	SELECT 1 FROM dual

Request example

{
  "sql": "SELECT 1 FROM dual",
  "datasourceId": "ds-dkl5x56dhbv6"
}

The request body above is from an actual call made at 2026-08-31 16:32:30 (UTC+8) against an Oracle data source and executes a read-only query. Use SQL syntax supported by the target data source. If the SQL depends on a database or schema context, pass the corresponding actual databaseName or schemaName for the target data source.

Response parameters

Parameter	Type	Description	Example
success	Boolean	Whether the request was successful.	true
requestId	String	OpenAPI request ID.	Lm1d3ICW-ekllfZXnejij1TIdeia6KON
data	Object	Execution result.	N/A
data.decision	String	Execution decision: EXECUTED, REJECTED, NEED_CONFIRMATION, NEED_SQL_TASK, or FAILED.	EXECUTED
data.datasourceId	String	Data source ID.	ds-dkl5x56dhbv6
data.databaseName	String	Database name. May be empty or absent when it was not passed or does not apply to the data source.	Not returned
data.schemaName	String	Schema name. May be empty or absent when it was not passed or does not apply to the data source.	Not returned
data.checkResults	Array	Rule-check and permission-precheck summary.	[{"hasError":false,"hasWarn":false,"allowSubmit":true,"violateList":[]}]
data.resultSets	Array	SQL result-set preview.	[{"sqlId":"QgjvEenHoLvMsbvbhuVWPdCyKJaoTGKY","status":"success","columns":[{"name":"1","type":"NUMBER"}],"rows":[{"col1":"1"}],"affectedRows":-1,"rowCount":1,"elapsedTimeMs":32}]
message	String	Error message when the request fails.	N/A

Read-only queries can be executed directly. High-risk SQL or SQL controlled by a workflow may return NEED_SQL_TASK. When decision is not EXECUTED, follow the returned decision and precheck details; do not treat the request as successfully executed.

data.checkResults fields

Parameter	Type	Description	Example
data.checkResults[].hasError	Boolean	Whether a blocking Error, Syntax, or Permission issue exists.	false
data.checkResults[].hasWarn	Boolean	Whether a Warning, Index, or other advisory item exists.	false
data.checkResults[].allowSubmit	Boolean	Whether subsequent processing may be submitted.	true
data.checkResults[].violateList	Array	List of rule violations found during checking.	[]

data.resultSets fields

Parameter	Type	Description	Example
data.resultSets[].sqlId	String	Identifier of the SQL execution.	QgjvEenHoLvMsbvbhuVWPdCyKJaoTGKY
data.resultSets[].status	String	Result-set status.	success
data.resultSets[].columns	Array	Returned column information.	[{"name":"1","type":"NUMBER"}]
data.resultSets[].rows	Array	Returned row data.	[{"col1":"1"}]
data.resultSets[].affectedRows	Integer	Number of affected rows.	-1
data.resultSets[].rowCount	Integer	Number of returned rows.	1
data.resultSets[].elapsedTimeMs	Integer	SQL execution time in milliseconds.	32

Objects in the columns array contain these fields:

Parameter	Type	Description	Example
data.resultSets[].columns[].name	String	Column name.	1
data.resultSets[].columns[].type	String	Column type.	NUMBER

Successful response example

{
  "success": true,
  "requestId": "Lm1d3ICW-ekllfZXnejij1TIdeia6KON",
  "data": {
    "decision": "EXECUTED",
    "datasourceId": "ds-dkl5x56dhbv6",
    "checkResults": [
      {
        "hasError": false,
        "hasWarn": false,
        "allowSubmit": true,
        "violateList": []
      }
    ],
    "resultSets": [
      {
        "sqlId": "QgjvEenHoLvMsbvbhuVWPdCyKJaoTGKY",
        "status": "success",
        "columns": [
          {
            "name": "1",
            "type": "NUMBER"
          }
        ],
        "rows": [
          {
            "col1": "1"
          }
        ],
        "affectedRows": -1,
        "rowCount": 1,
        "elapsedTimeMs": 32
      }
    ]
  }
}