Help Center/ DataArts Fabric/ API Reference/ APIs/ SQL APIs/ Creating a SQL Session
Updated on 2025-09-15 GMT+08:00
View PDF
Share

Creating a SQL Session

Function

This API is used to create a SQL session. You can call this API to create a SQL session at a SQL endpoint by entering the endpoint ID and LakeFormation configuration. The API returns the session information. This API is synchronous with no accompanying APIs or specific scenarios.

URI

POST /v1/workspaces/{workspace_id}/sessions

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

endpoint_id

Yes

String

  • Definition: endpoint ID.

  • Constraints: N/A.

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

  • Default Value: N/A.

lake_formation_config

Yes

LakeFormationInfo object

Definition: LakeFormation information.

Constraints: N/A.

wait_timeout

No

Integer

Definition: Waiting time for creating a session, in seconds.

Constraints: N/A.

Range: [300, 7200].

Default Value: N/A.
Table 4 LakeFormationInfo

Parameter

Mandatory

Type

Description

instance_id

Yes

String

Definition: LakeFormation instance ID.

Constraints: N/A.

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

Default Value: N/A.

catalog

Yes

String

Definition: LakeFormation catalog.

Constraints: N/A.

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

Default Value: N/A.

Response Parameters

Status code: 200

Table 5 Response body parameters

Parameter

Type

Description

session_id

String

Definition: Session ID.

Constraints: N/A.

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

Default Value: N/A.

status

String

Definition: Session status.

Constraints: N/A.

Range: [0, 64].

Default Value: N/A.

Status code: 400

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: 401

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: 404

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: 408

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.

Status code: 500

Table 10 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

Create a SQL session. You can call this API to create a SQL session at a SQL endpoint by entering the endpoint ID and LakeFormation configuration. The API returns the session information. This API is synchronous with no accompanying APIs or specific scenarios.

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

{
  "endpoint_id" : "b935d0ef-f4eb-4b95-aff1-9d33ae9f57b6",
  "lake_formation_config" : {
    "instance_id" : "0b5633ba2b904511ad514346f4d23d4b",
    "catalog" : "string"
  }
}

Example Responses

Status code: 200

A session is queried.

{
  "session_id" : "ac8111bf-3601-4905-8ddd-b41d3e636a4e",
  "status" : "RUNNING"
}

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

A session is queried.

400

BadRequest

401

Unauthorized

403

Forbidden

404

NotFound

408

Request Time-out

500

InternalServerError

Error Codes

See Error Codes.

Parent topic: SQL APIs