Skip to main content

Job

Use the Job API to get information about a specific job and cancel a running job.

note

To retrieve results for a specific job, use the Job Results endpoint.

Job Object 
{
  "jobState": "COMPLETED",
  "rowCount": 1003904,
  "errorMessage": "",
  "startedAt": "2022-12-13T18:34:14.069Z",
  "endedAt": "2022-12-13T18:35:09.963Z",
  "acceleration": {
    "reflectionRelationships": [
      {
        "datasetId": "ef99ab32-aa47-4f4c-4d1c-d40f8035b846",
        "reflectionId": "63fd1c83-5cde-4133-9e2d-60543550580a",
        "relationship": "CONSIDERED"
      },
      {
        "datasetId": "596c489c-7949-485b-92a9-c32a4cb51fa2",
        "reflectionId": "65747723-2319-430p-8a36-3d40b26f45ae",
        "relationship": "MATCHED"
      }
    ]
  },
  "queryType": "UI_RUN",
  "queueName": "LARGE",
  "queueId": "LARGE",
  "resourceSchedulingStartedAt": "2022-12-13T18:34:14.977Z",
  "resourceSchedulingEndedAt": "2022-12-13T18:34:14.995Z",
  "cancellationReason": ""
}

Job Attributes​

jobState String

The job's status. Values COMPLETED, CANCELED, and FAILED are final; other values are considered running states.

Valid Values: NOT_SUBMITTED, STARTING, RUNNING, COMPLETED, CANCELED, FAILED, CANCELLATION_REQUESTED, PLANNING, PENDING, METADATA_RETRIEVAL, QUEUED, ENGINE_START, EXECUTION_PLANNING, INVALID_STATE

Example: COMPLETED

rowCount Integer

For jobs with COMPLETED jobState, the number of rows the job returned. If jobState is not COMPLETED, the rowCount value is 0.

errorMessage String

For jobs with FAILED jobState, the error that caused the failure. For all other jobs, the errorMessage value is empty.

Example: Column 'user_id' not found in any table.

startedAt String

Timestamp when the job started.

endedAt String

Timestamp when the job ended.

acceleration Object

For jobs with applicable reflections, provides more information about the reflections and their relationships to the job. For jobs that do not have applicable reflections, the response does not include the acceleration object.

queryType String

Job type. If the job's queryType is not set, the value is UNKNOWN.

Valid Values: UI_RUN, UI_PREVIEW, UI_INTERNAL_PREVIEW, UI_INTERNAL_RUN, UI_EXPORT, ODBC, JDBC, REST, ACCELERATOR_CREATE, ACCELERATOR_DROP, UNKNOWN, PREPARE_INTERNAL, ACCELERATOR_EXPLAIN, UI_INITIAL_PREVIEW

Example: UI_RUN

queueName String

Name of the workload management (WLM) queue to which the job was routed. The queueName attribute appears in the response but is not supported in Dremio.

Example: SMALL

queueId String

ID of the workload management (WLM) queue to which the job was routed. The queueId attribute appears in the response but is not supported in Dremio.

Example: SMALL

resourceSchedulingStartedAt String

Timestamp when the Dremio engine started scheduling the job.

resourceSchedulingEndedAt String

Timestamp when Dremio engine scheduling ended for the job.

cancellationReason String

For canceled jobs, the reason for the cancellation. For all other jobs, the cancellationReason value is empty.

Example: Query was cancelled due to low memory.

Attributes of the acceleration Object​

reflectionRelationships Array of Object

Information about the dataset, Reflection, and type of relationship for each applicable Reflection.

Attributes of Objects in the reflectionRelationships Array​

datasetId String (UUID)

UUID of the dataset.

reflectionId String (UUID)

UUID for the reflection.

relationship String

Type of relationship between the reflection and the job. See Relationships between Reflections and Jobs for more information.

Valid Values: CONSIDERED, MATCHED, CHOSEN

Example: MATCHED

Retrieve a Job​

Method and URL 
GET /v0/projects/{project_id}/job/{id}

Parameters​

project_id Path   String (UUID)

id Path   String (UUID)

UUID for the job to retrieve. Get the job ID from responses to SQL API requests.

Examples​

Request 
curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/job/$JOB_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'
Response for a COMPLETED Job 
{
  "jobState": "COMPLETED",
  "rowCount": 1003904,
  "errorMessage": "",
  "startedAt": "2022-12-13T18:34:14.069Z",
  "endedAt": "2022-12-13T18:35:09.963Z",
  "acceleration": {
    "reflectionRelationships": [
      {
        "datasetId": "ef99ab32-aa47-4f4c-4d1c-d40f8035b846",
        "reflectionId": "63fd1c83-2319-5962-8a36-60543550580a",
        "relationship": "CONSIDERED"
      },
      {
        "datasetId": "596c489c-7949-485b-92a9-c32a4cb51fa2",
        "reflectionId": "65747723-4133-9e2d-3k86-3d40b26f45ae",
        "relationship": "MATCHED"
      }
    ]
  },
  "queryType": "UI_RUN",
  "queueName": "LARGE",
  "queueId": "LARGE",
  "resourceSchedulingStartedAt": "2022-12-13T18:34:14.977Z",
  "resourceSchedulingEndedAt": "2022-12-13T18:34:14.995Z",
  "cancellationReason": ""
}
Response for a CANCELED Job 
{
  "jobState": "CANCELED",
  "rowCount": 0,
  "errorMessage": "",
  "startedAt": "2023-01-05T21:04:40.743Z",
  "endedAt": "2023-01-05T21:06:35.257Z",
  "queryType": "UI_RUN",
  "queueName": "SMALL",
  "queueId": "SMALL",
  "resourceSchedulingStartedAt": "2023-01-05T21:04:40.932Z",
  "resourceSchedulingEndedAt": "2023-01-05T21:06:21.698Z",
  "cancellationReason": "Query cancelled by user 'USERNAME'"
}
Response for a FAILED Job 
{
  "jobState": "FAILED",
  "rowCount": 0,
  "errorMessage": "UNSUPPORTED_OPERATION ERROR: Unable to coerce from the file's data type \"double\" to the column's data type \"boolean\" in table \"Samples.samples.dremio.com.NYC-taxi-trips\", column \"fare_amount\" and file \"/samples.dremio.com/NYC-taxi-trips/1_1_0.parquet\"\n\nSqlOperatorImpl TABLE_FUNCTION\nLocation 1:9:5\nFragment 1:0\n\n[Error Id: fb88bb72-3fe1-45bc-9c32-207383c8e94b on 172.31.25.153:0]\n\n",
  "startedAt": "2023-01-05T21:15:26.049Z",
  "endedAt": "2023-01-05T21:17:21.976Z",
  "queryType": "UI_PREVIEW",
  "queueName": "LARGE",
  "queueId": "LARGE",
  "resourceSchedulingStartedAt": "2023-01-05T21:15:26.222Z",
  "resourceSchedulingEndedAt": "2023-01-05T21:17:10.877Z",
  "cancellationReason": ""
}
Response for a RUNNING Job 
{
  "jobState": "RUNNING",
  "rowCount": 1014881162,
  "errorMessage": "",
  "startedAt": "2023-02-01T21:57:27.227Z",
  "queryType": "ACCELERATOR_CREATE",
  "queueName": "REFLECTION_LARGE",
  "queueId": "REFLECTION_LARGE",
  "resourceSchedulingStartedAt": "2023-02-01T21:57:27.491Z",
  "resourceSchedulingEndedAt": "2023-02-01T21:57:27.508Z",
  "cancellationReason": ""
}

Response Status Codes​

200   OK

400   Bad Request

403   Forbidden

404   Not Found

Cancel a Running Job​

note

Canceling a job does not delete the job object. You can still retrieve job objects for canceled jobs.

Method and URL 
POST /v0/projects/{project_id}/job/{id}/cancel

Parameters​

project_id Path   String (UUID)

id Path   String (UUID)

UUID for the job to cancel. Get the job ID from responses to SQL API requests.

Example​

Request 
curl -X POST "https://api.dremio.cloud/v0/projects/$PROJECT_ID/job/$JOB_ID/cancel" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes​

204   No Content

400   Bad Request

403   Forbidden

404   Not Found