Creating a SQL Job

Function

This API is used to create a Flink streaming SQL job.

Authorization

Each account has full permissions to call all APIs, but its IAM users need permission assignments to do so. For specific permission requirements, refer to Permissions Policies and Supported Actions.

URI

URI format
POST /v1.0/{project_id}/streaming/sql-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 a project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request parameters
Parameter	Mandatory	Type	Description
name	Yes	String	Job name. The value can contain up to 57 characters.
desc	No	String	Job description. Length range: 0 to 512 characters.
template_id	No	Integer	Template ID. If both template_id and sql_body are specified, sql_body is used. If template_id is specified but sql_body is not, fill sql_body with the template_id value.
queue_name	No	String	Queue name. 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: 1,024 x 1,024 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. Sum of the number of compute units and job manager CUs of DLI. CU is also the billing unit of DLI. One CU equals one vCPU and 4 GB of memory. The value is the number of CUs required for job running and cannot exceed the number of CUs in the bound queue. For details about how to set the number of CUs of JobManager, see manager_cu_number.
parallel_number	No	Integer	Number of parallel jobs set by a user. The default value is 1. Number of Flink SQL jobs that run at the same time. Properly increasing the number of parallel threads improves the overall computing capability of the job. However, the switchover overhead caused by the increase of threads must be considered. This value cannot be greater than four times the compute units (number of CUs minus the number of JobManager CUs). For details about how to set the number of JobManager CUs, see manager_cu_number.
checkpoint_enabled	No	Boolean	Whether to enable the automatic job snapshot function. Options: true: Enable this function. false: Do not enable this function. Default value: false.
checkpoint_mode	No	Integer	Snapshot mode. Options: 1: ExactlyOnce, meaning data is consumed only once. 2: AtLeastOnce, meaning data is consumed at least once. Default value: 1.
checkpoint_interval	No	Integer	Snapshot interval. The unit is second. The default value is 10.
obs_bucket	No	String	OBS bucket where users are authorized to save the snapshot. This parameter is valid only when checkpoint_enabled is set to true. OBS bucket 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 this 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	Retention time of the idle state. The unit is second. The default value is 3600.
job_type	No	String	Job type. The options include flink_sql_job and flink_opensource_sql_job. The default value is flink_opensource_sql_job. If run_mode is set to exclusive_cluster, job_type must be set to flink_sql_job or flink_opensource_sql_job. If run_mode is set to shared_cluster, job_type must be set to flink_sql_job.
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. For Flink 1.15 or later, only OBS packages can be selected when creating jobs, and DLI packages are not supported.
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_numbertm_cus)/(cu_number-manager_cu_number)**.
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.
tags	No	Array of objects	Label of a Flink SQL job. For details, see Table 3.
runtime_config	No	String	Customizes optimization parameters when a Flink job is running.
flink_version	No	String	Flink version.
execution_agency_urn	No	String	Name of the agency authorized to DLI. This parameter is configurable in Flink 1.15.
resource_config_version	No	String	Resource configuration version. The value can be v1 or v2. The default value is v1. Compared with the v1 template, the v2 template does not support the setting of the number of CUs. The v2 template supports the setting of Job Manager Memory and Task Manager Memory. v1: applicable to Flink 1.12 and 1.15. v2: applicable to Flink 1.15 and 1.17. You are advised to use the parameter settings of v2.
resource_config	No	Object	Resource configuration of a Flink job. For detailed parameter descriptions, refer to Table 4. When the resource configuration version is v2, the configuration takes effect; when the resource configuration version is v1, the configuration is invalid.

**Table 3** tags parameters
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. NOTE: A tag key can contain up to 128 characters, cannot start or end with a space, and cannot start with _sys_. Only letters, digits, spaces, and the following special characters are allowed: _.:+-@
value	Yes	String	Tag value NOTE: A tag value can contain up to 255 characters. Only letters, digits, spaces, and the following special characters are allowed: _.:+-@

**Table 4** resource_config parameters
Parameter	Mandatory	Type	Description
max_slot	No	integer	Number of parallel tasks that a single TaskManager can support. Each task slot can execute one task in parallel. Increasing task slots enhances the parallel processing capacity of the TaskManager but also increases resource consumption. The number of task slots is linked to the CPU count of the TaskManager since each CPU can offer one task slot. By default, a single TM slot is set to 1. The minimum parallelism must not be less than 1.
parallel_number	No	integer	Number of tasks concurrently executed by each operator in a job. The default value is 1.
jobmanager_resource_spec	No	Object	JobManager resource specifications. For details about the parameters, see Table 5.
taskmanager_resource_spec	No	Object	TaskManager resource specifications. For details about the parameters, see Table 6.

**Table 5** jobmanager_resource_spec parameters
Parameter	Mandatory	Type	Description
cpu	No	double	Number of CPU cores available for JobManager. The default value is 1.0 CPU core, with a minimum of no less than 0.5 CPU cores. If the current job is running on a basic edition elastic resource pool (16–64 CUs), it is recommended that the JobManager's CPU value does not exceed 2 to avoid resource scheduling failures during job execution.
memory	No	string	Memory that can be used by JobManager, in MB or GB. The default unit is GB. The default value is 4 GB, and the minimum value is 2 GB.

**Table 6** taskmanager_resource_spec parameters
Parameter	Mandatory	Type	Description
cpu	No	double	Number of CPU cores available for TaskManager. The default value is 1.0 CPU core, with a minimum of no less than 0.5 CPU cores. If the current job is running on a basic edition elastic resource pool (16–64 CUs), it is recommended that the TaskManager's CPU value does not exceed 2 to avoid resource scheduling failures during job execution.
memory	No	string	Memory that can be used by TaskManager, in MB or GB. The default unit is GB. The default value is 4 GB, and the minimum value is 2 GB.

Response Parameters

**Table 7** Response parameters
Parameter	Mandatory	Type	Description
is_success	No	String	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 the job status. For details, see Table 8.

**Table 8** job parameters
Parameter	Mandatory	Type	Description
job_id	Yes	Long	Job ID.
status_name	No	String	Name of job status. For details, see the description of the status field in Querying Job Details.
status_desc	No	String	Status description. Causes and suggestions for the abnormal status.

Example Request

Use the template whose ID is 100000 to create a Flink SQL job named myjob. The job runs in dedicated mode on the testQueue queue.

{
    "name": "myjob",
    "desc": "This is a job used for counting characters.",
    "template_id": 100000,
    "queue_name": "testQueue",
    "sql_body": "select * from source_table",
    "run_mode": "exclusive_cluster",
    "cu_number": 2,
    "parallel_number": 1,
    "checkpoint_enabled": false,
    "checkpoint_mode": "exactly_once",
    "checkpoint_interval": 0,
    "obs_bucket": "my_obs_bucket",
    "log_enabled": false,
    "restart_when_exception": false,
    "idle_state_retention": 3600,
    "job_type": "flink_sql_job",
    "dirty_data_strategy": "0",
    "execution_agency_urn": "myAgencyName",
    "udf_jar_url": "group/test.jar"
}

Example Response

{
    "is_success": "true",
    "message": "A DLI job is created successfully.",
    "job": {
        "job_id": 148,
        "status_name": "job_init",
        "status_desc": ""
    }
}

Status Codes

Table 9 describes status codes.

**Table 9** Status codes
Status Code	Description
200	The job is created successfully.
400	The input parameter is invalid.

Error Codes

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

Parent topic: Flink Job-related APIs

Previous topic: Flink Job-related APIs

Next topic: Updating a SQL Job