On this page

    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 , ENQUEUED , 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

    Array

    Lists 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. Read Relationships between Reflections and Jobs for information about the relationship types.

    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' \
    -H 'Authorization: Bearer <personal access token>' \
    -H 'Content-Type: application/json'
    
    Example Response
    {
      "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": ""
    }
    

    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 information. You can still retrieve job information 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' \
    -H 'Authorization: Bearer <personal access token>' \
    -H 'Content-Type: application/json'
    
    Example response
    No response
    

    Responses

    204

    No Content

    400

    Bad Request

    403

    Forbidden

    404

    Not Found