Updated on 2023-11-27 GMT+08:00

Updating a SQL Job

Function

This API is used to modify a Flink SQL job.

URI

  • URI format

    PUT /v1.0/{project_id}/streaming/sql-jobs/{job_id}

  • Parameter description
    Table 1 URI parameters

    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.

    job_id

    Yes

    Long

    Job ID. Refer to Creating a SQL Job to obtain the value.

Request

Table 2 Request parameters

Parameter

Mandatory

Type

Description

name

No

String

Name of a job. Length range: 0 to 57 characters.

desc

No

String

Job description. Length range: 0 to 512 characters.

queue_name

No

String

Name of a queue. The value can contain 0 to 128 characters.

sql_body

No

String

Stream SQL statement, which includes at least the following three parts: source, query, and sink. Length range: 0 to 1024x1024 characters.

run_mode

No

String

Job running mode. The options are as follows:

  • shared_cluster: indicates that the job is running on a shared cluster.
  • exclusive_cluster: indicates that the job is running on an exclusive cluster.
  • edge_node: indicates that the job is running on an edge node.

The default value is shared_cluster.

cu_number

No

Integer

Number of CUs selected for a job. The default value is 2.

parallel_number

No

Integer

Number of parallel jobs set by a user. The default value is 1.

checkpoint_enabled

No

Boolean

Whether to enable the automatic job snapshot function.

  • true: indicates to enable the automatic job snapshot function.
  • false: indicates to disable the automatic job snapshot function.
  • Default value: false

checkpoint_mode

No

Integer

Snapshot mode. There are two options:

  • 1: ExactlyOnce, indicates that data is processed only once.
  • 2: at_least_once, indicates that data is processed at least once.

The default value is 1.

checkpoint_interval

No

Integer

Snapshot interval. The unit is second. The default value is 10.

obs_bucket

No

String

OBS path where users are authorized to save the snapshot. This parameter is valid only when checkpoint_enabled is set to true.

OBS path where users are authorized to save the snapshot. This parameter is valid only when log_enabled is set to true.

log_enabled

No

Boolean

Whether to enable the function of uploading job logs to users' OBS buckets. The default value is false.

smn_topic

No

String

SMN topic. If a job fails, the system will send a message to users subscribed to the SMN topic.

restart_when_exception

No

Boolean

Whether to enable the function of automatically restarting a job upon job exceptions. The default value is false.

idle_state_retention

No

Integer

Expiration time, in seconds. The default value is 3600.

edge_group_ids

No

Array of Strings

List of edge computing group IDs. Use commas (,) to separate multiple IDs.

dirty_data_strategy

No

String

Dirty data policy of a job.

  • 2:obsDir: Save. obsDir specifies the path for storing dirty data.
  • 1: Trigger a job exception
  • 0: Ignore

The default value is 0.

udf_jar_url

No

String

Name of the resource package that has been uploaded to the DLI resource management system. The UDF Jar file of the SQL job is specified by this parameter.

manager_cu_number

No

Integer

Number of CUs in the JobManager selected for a job. The default value is 1.

tm_cus

No

Integer

Number of CUs for each TaskManager. The default value is 1.

tm_slot_num

No

Integer

Number of slots in each TaskManager. The default value is (parallel_number*tm_cus)/(cu_number-manager_cu_number).

operator_config

No

String

Degree of parallelism (DOP) of an operator.

resume_checkpoint

No

Boolean

Whether the abnormal restart is recovered from the checkpoint.

resume_max_num

No

Integer

Maximum number of retry times upon exceptions. The unit is times/hour. Value range: -1 or greater than 0. The default value is -1, indicating that the number of times is unlimited.

static_estimator_config

No

String

Traffic or hit ratio of each operator, which is a string in JSON format. Example:

{"operator_list":[{"id":"0a448493b4782967b150582570326227","rate_factor":0.55},{"id":"6d2677a0ecc3fd8df0b72ec675edf8f4","rate_factor":1},{"id":"ea632d67b7d595e5b851708ae9ad79d6","rate_factor":0.55},{"id":"bc764cd8ddf7a0cff126f51c16239658","output_rate":2000}]}

runtime_config

No

String

Customizes optimization parameters when a Flink job is running.

flink_version

No

String

Flink version. Currently, only 1.10 and 1.12 are supported.

Response

Table 3 Response parameters

Parameter

Mandatory

Type

Description

is_success

No

Boolean

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

message

No

String

Message content.

job

No

Object

Information about job update. For details, see Table 4.

Table 4 job parameters

Parameter

Mandatory

Type

Description

update_time

No

Long

Job update time, expressed by milliseconds

Example Request

Update an existing SQL job. The updated job is named myjob and runs on testQueue in shared mode.

{
    "name": "myjob",
    "desc": "My first job",
    "queue_name": "testQueue",
    "sql_body": "select * from source_table",
    "run_mode": "shared_cluster",
    "cu_number": 4,
    "parallel_number": 4,
    "checkpoint_enabled": false,
    "checkpoint_mode": "exactly_once",
    "checkpoint_interval": 10,
    "obs_bucket": "",
    "log_enabled": false,
    "smn_topic": "",
    "restart_when_exception": false,
    "idle_state_retention": 3600,
    "edge_group_ids": [
        "62de1e1c-066e-48a8-a79d-f461a31b2ee1",
        "2eb00f85-99f2-4144-bcb7-d39ff47f9002"
    ],
    "dirty_data_strategy": "0",
    "udf_jar_url": "group/test.jar"
}

Example Response

{
    "is_success": "true",
    "message": "The job is updated successfully.",
    "job": {
        "update_time": 1578905682534
    }
}

Status Codes

Table 5 describes status codes.

Table 5 Status codes

Status Code

Description

200

The job is updated successfully.

400

The input parameter is invalid.

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.