Updated on 2024-03-15 GMT+08:00

Querying All Jobs

Function

This API is used to query information about all jobs in the current project.

URI

  • URI format

    GET /v1.0/{project_id}/jobs

  • Parameter description
    Table 1 URI parameter

    Parameter

    Mandatory

    Type

    Description

    project_id

    Yes

    String

    Project ID, which is used for resource isolation. For details about how to obtain its value, see Obtaining a Project ID.

    Table 2 query parameter description

    Parameter

    Mandatory

    Type

    Description

    page-size

    No

    Integer

    Maximum number of jobs displayed on each page. The value range is as follows: [1, 100]. The default value is 50.

    current-page

    No

    Integer

    Current page number. The default value is 1.

    start

    No

    Long

    Queries the jobs executed later than the time specified by this parameter. The time is a UNIX timestamp in milliseconds.

    end

    No

    Long

    Queries the jobs executed earlier than the time specified by this parameter. The time is a UNIX timestamp in milliseconds.

    job-type

    No

    String

    Type of a job to be queried. Job types include DDL, DCL, IMPORT, EXPORT, QUERY, INSERT, DATA_MIGRATION, UPDATE, DELETE, RESTART_QUEUE, and SCALE_QUEUE. To query all types of jobs, enter ALL.

    job-status

    No

    String

    Status of the job to be queried.

    job-id

    No

    String

    ID of the job to be queried. You can get the value by calling Submitting a SQL Job (Recommended).

    queue_name

    No

    String

    Specifies queue_name as the filter to query jobs running on the specified queue.

    sql_pattern

    No

    String

    Specifies the SQL segment as the filter. It is case insensitive.

    order

    No

    String

    Specifies the job sorting mode. The default value is start_time_desc (job submission time in descending order). Four sorting modes are supported: duration_desc (job running duration in descending order), duration_asc (job running duration in ascending order), start_time_desc (job submission time in descending order), and start_time_asc (job submission time in ascending order).

    engine-type

    No

    String

    Engine type.

    owner

    No

    String

    User who submits a job.

    tags

    No

    String

    Queue tags for the search. You can specify multiple tags in key=value format.

    • Request with one specified tag

    For example, GET /v1.0/{project_id}/jobs? tags=k1%3Dv1

    In this example, = needs to be escaped to %3D, k1 indicates the tag key, and v1 indicates the tag value.

    • Request with more than one tag

    Separate tags with commas (,) and convert the commas (,) to %2C, for example, GET /v1.0/{project_id}/jobs?. tags=k1%3Dv1%2Ck2%3Dv2.

    The equal sign (=) is escaped to %3D. k1 indicates a tag key, and v1 indicates the tag value. k2 indicates another tag key, and v2 indicates the tag value.

    Currently, only fuzzy query is supported. Exact query is not supported.

    The following is an example of the URL containing the query parameter:

    GET /v1.0/{project_id}/jobs?page-size={size}&current-page={page_number}&start={start_time}&end={end_time}&job-type={QUERY}&queue_name={test}&order={duration_desc}

Request

None

Response

Table 3 Response parameters

Parameter

Mandatory

Type

Description

is_success

Yes

Boolean

Indicates whether the request is successfully executed. Value true indicates that the request is successfully executed.

message

Yes

String

System prompt. If execution succeeds, the parameter setting may be left blank.

job_count

Yes

Integer

Indicates the total number of jobs.

jobs

Yes

Array of Objects

Indicates the information about a job. For details, see Table 4.

Table 4 jobs parameters

Parameter

Mandatory

Type

Description

job_id

Yes

String

Job ID.

job_type

Yes

String

Type of a job.

queue_name

Yes

String

Queue to which a job is submitted.

owner

Yes

String

User who submits a job.

start_time

Yes

Long

Time when a job is started. The timestamp is expressed in milliseconds.

duration

Yes

Long

Job running duration (unit: millisecond).

status

Yes

String

Status of a job, including LAUNCHING, RUNNING, FINISHED, FAILED, and CANCELLED.

input_row_count

No

Long

Number of records scanned during the Insert job execution.

bad_row_count

No

Long

Number of error records scanned during the Insert job execution.

input_size

Yes

Long

Size of scanned files during job execution.

result_count

Yes

Integer

Total number of records returned by the current job or total number of records inserted by the Insert job.

database_name

No

String

Name of the database where the target table resides. database_name is valid only for jobs of the Import and Export types.

table_name

No

String

Name of the target table. table_name is valid only for jobs of the Import and Export types.

with_column_header

No

Boolean

Import jobs, which record whether the imported data contains column names.

detail

Yes

String

JSON string of related columns queried using SQL statements.

statement

Yes

String

SQL statements of a job.

message

No

String

System prompt.

end_time

No

Long

Job end time. The timestamp is in milliseconds.

tags

No

Array of Objects

Job tags. For details, see Table 5.

output_byte

No

String

Number of output bytes of a job.

cpu_cost

No

String

Total CPU used by a job.

Table 5 tags parameters

Parameter

Mandatory

Type

Description

key

Yes

String

Tag key

value

Yes

String

Tag value

Example Request

None

Example Response

{
 "is_success": true,
  "message": "",
  "job_count": 1,
  "jobs": [
    {

      "detail": "{\"type\":\"struct\",\"fields\":[{\"name\":\"name\",\"type\":\"string\",\"nullable\":true,\"metadata\":{}},{\"name\":\"age\",\"type\":\"integer\",\"nullable\":true,\"metadata\":{}}]}",
      "duration": 17731,

      "end_time": 1502349821460,
      "input_size": 0,
      "job_id": "37286cc7-0508-4ffd-b636-951c8a5c75de",
      "job_type": "QUERY",
      "message": "",
      "owner": "tenant1",
      "queue_name": "queue1",
      "result_count": 3,
      "start_time": 1502349803729,
      "statement": "select * from t_json_002",
      "status": "FINISHED",
      "with_column_header": false
    }
  ]
}

Status Codes

Table 6 describes the status code.

Table 6 Status codes

Status Code

Description

200

The query is successful.

400

Request error.

500

Internal service error.

Error Codes

If an error occurs when this API is invoked, the system does not return the result similar to the preceding example, but returns the error code and error information. For details, see Error Codes.