Add Comments to an Asynchronous Job

When you submit an asynchronous job, you can use the comments request property to provide a description of the job. When you retrieve the completed job result, the comments field contains the submitted description.

Prerequisites

Before running the examples, obtain an OAuth access token. See, Obtain an OAuth Access Token.

Example: Submit a group-apply Job and Retrieve Its Comments

This example shows how to:

• Register the group.count script in the script repository.
• Submit an asynchronous group-apply job with a comment.
• Check the job status.
• Retrieve the completed job result and its comments.

Register the Group-Apply Script

The group.count script counts the number of records for each species in the IRIS dataset.

Run the following PL/SQL block in a SQL session connected to the database to register group.count in the script repository:

BEGIN
  sys.rqScriptCreate(
    'group.count',
    'function(dat) {
       x <- data.frame(table(dat$Species))
       names(x) <- c("Species", "Count")
       x}',
    TRUE, TRUE
  );
END;
/

The arguments specify the following:

• The first argument specifies the name under which the script is stored in the repository.
• The second argument contains the R function definition as a string.
• The third argument, V_GLOBAL, controls whether the script is globally accessible. Setting it to TRUE makes the script globally accessible.

• The fourth argument, V_OVERWRITE, controls whether an existing script with the same name is replaced. Setting it to TRUE replaces the existing script.

Submit the job

The following request submits an asynchronous group-apply job that counts the records for each species in the IRIS dataset. The comments property provides a description of the job.

curl -ikX POST \
  --header "Authorization: Bearer ${token}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  -d '{
    "input": "IRIS",
    "groupBy": "Species",
    "comments": "IRIS dataset: counting samples grouped by Species",
    "asyncFlag": true
  }' \
  "<oml-cloud-service-location-url>/oml/api/r-scripts/v2/group-apply/group.count/RQSYS"

The response has HTTP status 201 Created and includes a Location header containing the job ID:

HTTP/2 201 Created
server: nginx/1.14.1
date: Thu, 23 Jul 2026 15:46:25 GMT
content-length: 0
strict-transport-security: max-age=31536000;includeSubDomains
x-content-type-options: nosniff
set-cookie: JSESSIONID=node0a2ukgrg0zetn34usmt4qdu7p16.node0;
Path=/oml; Secure; HttpOnly
expires: Thu, 01 Jan 1970 00:00:00 GMT
location: https://<oml-cloud-service-location-url>/oml/api/r-scripts/v2/jobs/<job_id>

Check the job status

Use the job ID returned in the Location header to check the job status. A 202 Accepted response indicates that the job is still running. When the job completes, the response is 302 Found and includes the result URL in the Content-Location header.

curl -ik -X GET \
  --header "Authorization: Bearer ${token}" \
  --header "Accept: application/json" \
  "<oml-cloud-service-location-url>/oml/api/r-scripts/v2/jobs/<job_id>"

Check the status until the job completes. When the job is complete, it returns:

HTTP/2 302 Found
server: nginx/1.14.1
date: Thu, 23 Jul 2026 15:50:43 GMT
content-length: 0
strict-transport-security: max-age=31536000;includeSubDomains
x-content-type-options: nosniff
content-location: https://<oml-cloud-service-location-url>/oml/api/r-scripts/v2/jobs/<job_id>/result

Retrieve the job result

Use the result URL to retrieve the completed job result:

curl -ik -X GET \
  --header "Authorization: Bearer ${token}" \
  --header "Accept: application/json" \
  "<oml-cloud-service-location-url>/oml/api/r-scripts/v2/jobs/<job_id>/result"

The result field contains the number of records for each species in the IRIS dataset. The comments field contains the comment provided when the job was submitted.

{
  "result": [
    {
      "Count": 50,
      "Species": "setosa"
    },
    {
      "Count": 50,
      "Species": "versicolor"
    },
    {
      "Count": 50,
      "Species": "virginica"
    }
  ],
  "comments": "IRIS dataset: counting samples grouped by Species",
  "status": "FINISH"
}

In this example, IRIS dataset: counting samples grouped by Species is the comment specified in the request.

Submit Other Asynchronous Jobs with Comments

You can also use the comments request property when submitting asynchronous jobs through other R function endpoints, such as do-eval, row-apply, and index-apply. Follow the same procedure described in the preceding example to submit the job, check its status, and retrieve the result and comments.