CreateSemanticJob-DataWorks(DataWorks)-阿里云帮助中心

Saves a reusable semantic job definition. If you use a single-file source, apply for and complete the attachment upload first. After creation, call RunSemanticJob with the returned Name.

Operation description

Scenarios

Creates and saves a reusable semantic job definition. This operation only saves the data source, resource group, and reference file configurations without immediately executing the job.

Recommended workflow

When Source.type=singleTableFile, call UploadSemanticFile first, use the returned Data.UploadUrl to complete the PUT upload, and then specify Data.FileId in ReferenceFileIds. Alternatively, you can provide a single accessible URI.
Configure Source, ProjectId, and ResourceGroupId, and then call this operation to save the job.
Use Data.Name from the response to call RunSemanticJob. After the job is complete, use DownloadSemanticResults to retrieve the output.

Before you begin

Name must be unique within the current tenant. The reference file quantity rules differ between single-file sources and other sources. For details, refer to the descriptions of the ReferenceFileIds and ReferenceFileUris fields.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request parameters

Parameter	Type	Required	Description	Example
Name	string	Yes	The semantic job name, which also serves as the job identifier for subsequent calls to RunSemanticJob, DeleteSemanticJob, ListSemanticJobRuns, and DownloadSemanticResults. The name must be unique within the current tenant.	semantic-job-demo
ProjectId	integer	No	The DataWorks workspace ID. This parameter is required for all Source.type values except singleTableFile. The Data.ProjectId in the creation result can be reused for GetSemanticJobDetail, GetSemanticJobLog, and KillSemanticJob.	100
ResourceGroupId	string	Yes	The ID of the resource group used to run the semantic job. RunSemanticJob does not accept this parameter and instead uses the resource group saved during creation.	rg-demo
Source	object	Yes	The input datasource config for the semantic node. The type field is required. This parameter specifies the data to be analyzed and is not the semantic_model YAML output. The domain field is a character string that serves as the identity of the business domain and focus of the node, such as sales. Supported types: 1) maxcompute: Use pinnedScopeInfo to specify the scope. Array elements contain type and name. When type=project, name is the MaxCompute project name. When type=schema, project is the project name and name is the schema name. For table-level scope, project is the project name, schema is optional, and name is the table name. 2) holo or starrocks: In addition to type, you must specify dataSourceName and dataSourceEnv, and pass ProjectId at the top level of the request. You can use pinnedScopeInfo to limit the scope to schemas or tables. The name element is the schema or table name, and the schema element for table-level scope is the database or schema. 3) singleTableFile: ProjectId is not required. For file reference rules, see ReferenceFileIds and ReferenceFileUris. After the node runs successfully, use DownloadSemanticResults to retrieve the semantic_model YAML and other result files. The example shows a MaxCompute project-level scope.	{"type":"maxcompute","domain":"sales","pinnedScopeInfo":[{"type":"project","name":"mc_project"}]}
ReferenceFileIds	array	No	The list of uploaded reference file IDs. When Source.type=singleTableFile, use either this parameter or ReferenceFileUris, and the selected array must contain exactly one non-empty element. The ID must come from Data.FileId returned by UploadSemanticFile, and only CSV or XLSX files are supported. For other Source.type values, you can pass multiple IDs. The service validates each ID during creation, and you can also pass ReferenceFileUris at the same time.
	string	No	The list of optional uploaded reference file IDs.	semantic-job-value
ReferenceFileUris	array	No	The list of reference file URIs accessible by the caller. When Source.type=singleTableFile, use either this parameter or ReferenceFileIds, and the selected array must contain exactly one non-empty URI. For other Source.type values, you can pass multiple URIs and also pass ReferenceFileIds at the same time. When using the upload path from UploadSemanticFile, pass Data.FileId after the PUT upload is complete instead of the short-lived UploadUrl.
	string	No	The list of optional accessible reference file URIs.	semantic-job-value

Construct the call parameters based on the descriptions of each request field.

Response elements

Element	Type	Description	Example
	object	The standard response for creating a semantic job. Data contains the saved job definition. Subsequent calls use the Name, ProjectId, and reference file information from Data.
RequestId	string	The request ID. Used for locating logs and troubleshooting issues.	676271D6-53B4-57BE-89FA-72F7AE1418DF
Success	boolean	Indicates whether the request was successful.
Data	object	The saved semantic job definition. Use Data.Name to call RunSemanticJob, DeleteSemanticJob, ListSemanticJobRuns, and DownloadSemanticResults.
Id	integer	The internal unique ID of the job definition, which identifies the job created by this call.	1
Name	string	The saved job name. Use this value for subsequent operations such as running, deleting, querying run records, and downloading results.	semantic-job-demo
UserId	string	The identifier of the user who created the job.	user-demo
Creator	string	The job creator identifier, equivalent to UserId, used to display creation ownership.	user-demo
ProjectId	integer	The DataWorks workspace ID to which the job belongs. Use this value as the ProjectId for GetSemanticJobDetail, GetSemanticJobLog, and KillSemanticJob.	100
Type	string	The saved Source.type data source type, used to quickly identify the job input type.	maxcompute
Source	object	The saved input datasource config, corresponding to the Source in the creation request. The data scope to be analyzed is determined based on this configuration at runtime.
ReferenceFileIds	array	The list of associated uploaded file IDs. For singleTableFile, the single file in this list is read at runtime.
	string	The FileId returned by UploadSemanticFile after the PUT upload is complete.	FID1
ReferenceFileUris	array	The list of associated external reference file URIs. For singleTableFile, the single file in this list is read at runtime.
	string	The accessible reference file URI provided by the caller.	https://example.com/reference.pdf
GmtCreate	integer	The creation time of the job definition, expressed as a UNIX timestamp in milliseconds.	1700000000000
GmtModified	integer	The last modification time of the job definition, expressed as a UNIX timestamp in milliseconds.	1700000000000
ResourceGroupId	string	The ID of the resource group that is used when running this job.	rg-demo

For the meanings of response fields and their relationships to subsequent calls, refer to the individual field descriptions.

Examples

Success response

JSON format

{
  "RequestId": "676271D6-53B4-57BE-89FA-72F7AE1418DF",
  "Success": false,
  "Data": {
    "Id": 1,
    "Name": "semantic-job-demo",
    "UserId": "user-demo",
    "Creator": "user-demo",
    "ProjectId": 100,
    "Type": "maxcompute",
    "Source": {
      "test": "test",
      "test2": 1
    },
    "ReferenceFileIds": [
      "FID1"
    ],
    "ReferenceFileUris": [
      "https://example.com/reference.pdf"
    ],
    "GmtCreate": 1700000000000,
    "GmtModified": 1700000000000,
    "ResourceGroupId": "rg-demo"
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.