Help Center/ DataArts Fabric/ API Reference/ APIs/ SQL APIs/ Executing a SQL Statement
Updated on 2025-09-15 GMT+08:00

Executing a SQL Statement

Function

This API is used to execute SQL statements within a specified session. You can call this API to execute SQL statements by providing inputs such as SQL statements, endpoint IDs, SQL session IDs, and binding parameters. It returns either the execution result or the statement ID. When calling this API, you can configure the input parameter is_sync to control whether statements are executed in synchronous or asynchronous mode. If statements are executed asynchronously, you need to use ShowSqlStatementResult to query the statement execution results. If statements are executed synchronously, the API waits for a period of time to receive the execution results. If the execution is complete, the execution results are returned. If the execution is not complete, the status is returned. You can use ShowSqlStatementResult to query the statement execution results.

URI

POST /v1/workspaces/{workspace_id}/sessions/statements

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

workspace_id

Yes

String

Definition: Workspace ID.

Constraints: N/A.

Range: 1 to 36 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: N/A.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

Definition: Tenant token.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

statement

Yes

String

Definition: SQL statement.

Constraints: N/A.

Range: [0, 10000000].

Default Value: N/A.

limit

No

Integer

Definition: Limit.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

session_id

Yes

String

Definition: Session ID.

Constraints: N/A.

Range: 1 to 36 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: N/A.

bindings

No

Array<Array<String>>

Definition: Parameter binding list.

Constraints: N/A.

Range: [0, 10000].

Default Value: N/A.

is_sync

No

Boolean

Definition: Whether an execution is synchronous or asynchronous.

Constraints: N/A.

Range: true: synchronous; false: asynchronous.

Default Value: N/A.

is_maintain_statement

No

Boolean

  • Definition: whether the statement is an O&M channel statement.

  • Constraints: N/A.

  • Range: true (It is an O&M channel statement) or false (It is not an O&M channel statement)

  • Default Value: N/A.

resultset_fetch_mode

No

String

  • Definition: how to return the result set.

  • Constraints: N/A.

  • Range: DEFAULT: The result set is returned directly. READ_OBS: The path of the result set in the bucket is returned instead of the result set.

  • Default Value: DEFAULT.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

-

String

Response information of the SQL statement execution, in string format. For details, see the Example Response.

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: [8, 36].

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

Status code: 401

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: [8, 36].

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

Status code: 404

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: [8, 36].

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

Status code: 408

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: [8, 36].

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

Status code: 500

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: [8, 36].

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: [2, 4096].

Default Value: N/A.

Example Requests

This API is used to execute SQL statements within a specified session. You can call this API to execute SQL statements by providing inputs such as SQL statements, endpoint IDs, SQL session IDs, and binding parameters. It returns either the execution result or the statement ID. When calling this API, you can configure the input parameter is_sync to control whether statements are executed in synchronous or asynchronous mode. If statements are executed asynchronously, you need to use ShowSqlStatementResult to query the statement execution results. If statements are executed synchronously, the API waits for a period of time to receive the execution results. If the execution is complete, the execution results are returned. If the execution is not complete, the status is returned. You can use ShowSqlStatementResult to query the statement execution results.

POST https://endpoint/v1/workspaces/{workspace_id}/sessions/statements

{
  "statement" : "select * from aaa",
  "limit" : 100,
  "session_id" : "string",
  "bindings" : [ [ "string" ] ],
  "is_maintain_statement" : false,
  "resultset_fetch_mode" : "DEFAULT",
  "is_sync" : true
}

Example Responses

Status code: 200

OK

{
  "status" : 1,
  "session_id" : "6399466e-8908-4c9d-8399-48479c8b06f7",
  "statement_id" : "49131d25-1824-4f29-860c-832bdd19dfd3"
}

Status code: 400

BadRequest

{
  "error_code" : "common.01000001",
  "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException"
}

Status code: 401

Unauthorized

{
  "error_code" : "APIG.1002",
  "error_msg" : "Incorrect token or token resolution failed"
}

Status code: 403

Forbidden

{
  "error" : {
    "code" : "403",
    "message" : "X-Auth-Token is invalid in the request",
    "title" : "Forbidden"
  },
  "error_code" : 403,
  "error_msg" : "X-Auth-Token is invalid in the request",
  "title" : "Forbidden"
}

Status code: 404

NotFound

{
  "error_code" : "common.01000001",
  "error_msg" : "response status exception, code: 404"
}

Status code: 408

Request Time-out

{
  "error_code" : "common.00000408",
  "error_msg" : "timeout exception occurred"
}

Status code: 500

InternalServerError

{
  "error_code" : "common.00000500",
  "error_msg" : "internal error"
}

Status Codes

Status Code

Description

200

OK

400

BadRequest

401

Unauthorized

403

Forbidden

404

NotFound

408

Request Time-out

500

InternalServerError

Error Codes

See Error Codes.