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 in running state.

Enum 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, rowCount value is 0.

Example 11

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

Date and time when the job started, in UTC format.

Example 2022-12-09T20:16:15.694Z

endedAt

String

Date and time when the job ended, in UTC format.

Example 2022-12-09T20:16:19.939Z

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.

Enum 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 Cloud.

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 Cloud.

Example SMALL

resourceSchedulingStartedAt

String

Date and time when the Dremio engine started scheduling the job.

Example 2022-12-09T20:16:16.141Z

resourceSchedulingEndedAt

String

Date and time when Dremio engine scheduling ended for the job.

Example 2022-12-09T20:16:16.162Z

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.

acceleration​

reflectionRelationships

[Object]

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

reflectionRelationships​

datasetId

String (UUID)

Unique identifier for the dataset associated with the reflection.

Example 596c489c-7949-485b-92a9-c32a4cb51fa2

reflectionId

String (UUID)

Unique identifier for the reflection.

Example 65747723-2319-430p-8a36-3d40b26f45ae

relationship

String

Type of relationship between the reflection and the job.

For more information, read Relationships between Reflections and Jobs.

Enum CONSIDERED, MATCHED, CHOSEN

Example MATCHED

Retrieve a Job​

Retrieve the specified job.

Method and URL
GET /v0/projects/{project-id}/job/{id}

Parameters​

project-id

path

String (UUID)

Unique identifier for the project where the job was run.

id

path

String (UUID)

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


Example Request
curl -X GET 'https://api.dremio.cloud/v0/projects/994508c4-5041-536b-ka63-09p98727a3c4/job/6j6c34cf-9drf-b07a-5ab7-abea69a66d00' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example 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": ""
}
Example 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'"
}
Example 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": ""
}
Example 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": ""
}

Responses​

200

OK

400

Bad Request

403

Forbidden

404

Not Found

Cancel a Running Job​

Cancel the specified 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)

Unique identifier for the project where the job was run.

id

path

String (UUID)

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


Example request
curl -X POST 'https://api.dremio.cloud/v0/projects/994508c4-5041-536b-ka63-09p98727a3c4/job/6j6c34cf-9drf-b07a-5ab7-abea69a66d00/cancel' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example response
No response

Responses​

204

No Content

400

Bad Request

403

Forbidden

404

Not Found