> > >

View a Job

This API retrieves information about a job.

Syntax

Operation	URI
Retrieves a job’s status.	`GET /api/v3/job/{id}`
Retrieve results for a completed job.	`GET /api/v3/job/{id}/results?offset={offset}&limit={limit}`

When retrieving the results for a completed job, The JobResults endpoint for a completed job supports pagination.

offset - Sets where you want to start from. Default: 0
limit - Determines how many rows are returned (maximum of 500). Default: 100

JobStatus Response Output

Output for the status of a job.

{
  "jobState": String PENDING, METADATA_RETRIEVAL, PLANNING, QUEUED, ENGINE_START, EXECUTION_PLANNING, STARTING, RUNNING, COMPLETED, CANCELED, FAILED]
  "queryType": String [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]
  "startedAt": String (RFC3339 date),
  "endedAt": String (RFC3339 date),
  "rowCount": Number [optional],
  "acceleration": JobAccelerationStatus [optional],
  "errorMessage": String [optional]
}

Name	Type	Description
jobState	String	The state of the job, will be either `PENDING`, `METADATA_RETRIEVAL`, `PLANNING`, `QUEUED`, `ENGINE_START`, `EXECUTION_PLANNING`, `STARTING`, `RUNNING`, `COMPLETED`, `CANCELED`, `FAILED`.
queryType	String	The type corresponding to what mechanism was used to submit this query, will be either `UI_RUN`, `UI_PREVIEW`, `UI_INTERNAL_PREVIEW`, `UI_INTERNAL_RUN`, `UI_EXPORT`, `ODBC`, `JDBC`, `REST`, `ACCELERATOR_CREATE`, `ACCELERATOR_DROP`, `UNKNOWN`, `PREPARE_INTERNAL`, `ACCELERATOR_EXPLAIN`, or `UI_INITIAL_PREVIEW`.
startedAt	String	RFC3339 date (example: `2017-10-27T21:08:22.858Z`) representing the datetime the query was started.
endedAt	String	RFC3339 date (example: `2017-10-27T21:08:22.858Z`) representing the datetime the query ended.
rowCount	Number	If the query is in `COMPLETED` state then the number of returned rows will be present.
acceleration	JobAccelerationStatus	Present if the query may have been accelerated.
errorMessage	String	If the query is in `FAILED` state will show the error that was recorded causing to the failure.

JobAccelerationStatus

When a query is run, reflections may be used to accelerate it. JobAccelerationStatus provides a list of relationships containing information about reflections that were detected as potentially applicable.

{
  "reflectionRelationships": [JobAccelerationRelationship]
}

JobAccelerationRelationship

Describes the relationship a reflection had regarding the job.

{
  "reflectionId": String,
  "datasetId": String,
  "relationship": String [CONSIDERED, MATCHED, CHOSEN]
}

CONSIDERED reflections are when the reflection is defined on a dataset that is used in the query but was determined to not cover the query (for example the reflection did not have a field that is used by the query).
MATCHED reflections are when a reflection could have been used to accelerate the query but Dremio determined that it would not provide any benefits or another reflection was determined to be a better choice.
CHOSEN reflections are when a reflection is used to accelerate the query. Note that multiple reflections can be used to accelerate queries.

JobResults Response Output

Output for the results of a successfully completed job.

{
  "rowCount": Number,
  "schema": [FieldSchema],
  "rows": [Json]
}

Name	Type	Description
rowCount	Number	The total number of rows for the job.
schema	[FieldSchema]	An array of FieldSchema definitions. Represents the schema of the data returned by the job.
rows	[Json]	The JSON representation of the requested rows.

FieldSchema

Represents the schema of a field. See Dataset for details.

Response Codes

400 - specified job is not in a completed state.
403 - user does not have permission to access the specified job.
404 - a job with the specified id could not be found.

Example: GET Job by ID

GET /job/{id} retrieves the status of a specific job. In this example, the Job ID, 23a4bf43-52aa-5d29-c473-0083c44fe700 from the SQL API example is used. In the SQL API example, a weapons_laws dataset was created in the SFIncidents space from the provided SF_Incidents2016.json Sample. Only Weapons Laws incidents are in the dataset. See the SQL API POST /sql for more details.

The following equivalent Dremio UI query on the weapons_laws dataset provides the same results as the SQL API example query.

SELECT * FROM weapons_laws WHERE PdDistrict = 'CENTRAL' LIMIT 3

Postman is used to generate the example.

HTTP request

GET localhost:9047/api/v3/job/23a4bf43-52aa-5d29-c473-0083c44fe700

Curl

curl -X GET \
  http://localhost:9047/api/v3/job/23a4bf43-52aa-5d29-c473-0083c44fe700 \
  -H 'Authorization: _dremioicmqi0aoro8o0el8rj0jfjh6n0' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 423f741e-6712-44ae-8347-dddf23a3795c' \
  -H 'cache-control: no-cache' \
  -d '{
	"sql": "SELECT * FROM SFIncidents.weapons_laws WHERE PdDistrict = '\''CENTRAL'\'' LIMIT 3"
}'

Python

import requests

url = "http://localhost:9047/api/v3/job/23a4bf43-52aa-5d29-c473-0083c44fe700"

payload = "{\n\t\"sql\": \"SELECT * FROM SFIncidents.weapons_laws WHERE PdDistrict = 'CENTRAL' LIMIT 3\"\n}"
headers = {
    'Authorization': "_dremioicmqi0aoro8o0el8rj0jfjh6n0",
    'Content-Type': "application/json",
    'cache-control': "no-cache",
    'Postman-Token': "73eeb96c-445d-45ee-b07f-4afd9799deb7"
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)

Response

{
    "jobState": "COMPLETED",
    "rowCount": 3,
    "errorMessage": "",
    "startedAt": "2019-02-06T20:17:00.137Z",
    "endedAt": "2019-02-06T20:17:00.792Z",
    "queryType": "REST",
    "queueName": "Low Cost User Queries",
    "queueId": "ae4e6e27-ff29-4a2b-a045-88189b8423a8",
    "resourceSchedulingStartedAt": "2019-02-06T20:17:00.413Z",
    "resourceSchedulingEndedAt": "2019-02-06T20:17:00.420Z",
    "cancellationReason": ""
}

Example: Get Job Results by ID

GET /api/v3/job/{id}/results retrieves the results (using the defaults) for a completed job.

In this example, the Job ID, 23a4bf43-52aa-5d29-c473-0083c44fe700 from the SQL API example is used. In the SQL API example, a weapons_laws dataset was created in the SFIncidents space from the provided SF_Incidents2016.json Sample. Only Weapons Laws incidents are in the dataset. See the SQL API POST /sql for more details.

The following equivalent Dremio UI query on the weapons_laws dataset provides the same results as the SQL API example query.

In this example, the SQL query limits the returned data. Alternatively, you could not set the limit in the SQL query, but this Job request with the limit option.

For example: GET /api/v3/job/{id}/results?limit=1

SELECT * FROM weapons_laws WHERE PdDistrict = 'CENTRAL' LIMIT 3

Postman is used to generate the example.

HTTP request

GET localhost:9047/api/v3/job/23a4bf43-52aa-5d29-c473-0083c44fe700/results

Curl

curl -X GET \
  http://localhost:9047/api/v3/job/23a4bf43-52aa-5d29-c473-0083c44fe700/results \
  -H 'Authorization: _dremioicmqi0aoro8o0el8rj0jfjh6n0' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: c5d31663-192f-4be2-9a86-2d8a42b8cc43' \
  -H 'cache-control: no-cache' \
  -d '{
	"sql": "SELECT * FROM SFIncidents.weapons_laws WHERE PdDistrict = '\''CENTRAL'\'' LIMIT 3"
}'

Python

import requests

url = "http://localhost:9047/api/v3/job/23a4bf43-52aa-5d29-c473-0083c44fe700/results"

payload = "{\n\t\"sql\": \"SELECT * FROM SFIncidents.weapons_laws WHERE PdDistrict = 'CENTRAL' LIMIT 3\"\n}"
headers = {
    'Authorization': "_dremioicmqi0aoro8o0el8rj0jfjh6n0",
    'Content-Type': "application/json",
    'cache-control': "no-cache",
    'Postman-Token': "cf48bbc7-4db1-4943-90a8-8cddca07205d"
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)

Response

{
    "rowCount": 3,
    "schema": [
        {
            "name": "IncidntNum",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Category",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Descript",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "DayOfWeek",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Date",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Time",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "PdDistrict",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Resolution",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Address",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "X",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Y",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Location",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "PdId",
            "type": {
                "name": "BIGINT"
            }
        }
    ],
    "rows": [
        {
            "IncidntNum": "160064938",
            "Category": "WEAPON LAWS",
            "Descript": "EXHIBITING DEADLY WEAPON IN A THREATING MANNER",
            "DayOfWeek": "Saturday",
            "Date": "2016-01-23",
            "Time": "11:08",
            "PdDistrict": "CENTRAL",
            "Resolution": "NONE",
            "Address": "1000 Block of HYDE ST",
            "X": "-122.417368206741",
            "Y": "37.7905094151595",
            "Location": "(37.7905094151595, -122.417368206741)",
            "PdId": 16006493812030
        },
        {
            "IncidntNum": "160090488",
            "Category": "WEAPON LAWS",
            "Descript": "EXHIBITING DEADLY WEAPON IN A THREATING MANNER",
            "DayOfWeek": "Sunday",
            "Date": "2016-01-31",
            "Time": "14:28",
            "PdDistrict": "CENTRAL",
            "Resolution": "NONE",
            "Address": "200 Block of SUTTER ST",
            "X": "-122.404013943546",
            "Y": "37.7897518225049",
            "Location": "(37.7897518225049, -122.404013943546)",
            "PdId": 16009048812030
        },
        {
            "IncidntNum": "160192307",
            "Category": "WEAPON LAWS",
            "Descript": "POSS OF FIREARM BY CONVICTED FELON/ADDICT/ALIEN",
            "DayOfWeek": "Saturday",
            "Date": "2016-03-05",
            "Time": "20:18",
            "PdDistrict": "CENTRAL",
            "Resolution": "ARREST, BOOKED",
            "Address": "POST ST / STOCKTON ST",
            "X": "-122.406775392392",
            "Y": "37.7884982866148",
            "Location": "(37.7884982866148, -122.406775392392)",
            "PdId": 16019230712080
        }
    ]
}

Example: Retrieving the results with limits

In this example, the Job ID, 23a4bf43-52aa-5d29-c473-0083c44fe700 is used to retrieve the results with the limit option set to one (1).

HTTP request

GET localhost:9047/api/v3/job/23a4bf43-52aa-5d29-c473-0083c44fe700/results?limit=1

Response

{
    "rowCount": 3,
    "schema": [
        {
            "name": "IncidntNum",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Category",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Descript",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "DayOfWeek",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Date",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Time",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "PdDistrict",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Resolution",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Address",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "X",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Y",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "Location",
            "type": {
                "name": "VARCHAR"
            }
        },
        {
            "name": "PdId",
            "type": {
                "name": "BIGINT"
            }
        }
    ],
    "rows": [
        {
            "IncidntNum": "160064938",
            "Category": "WEAPON LAWS",
            "Descript": "EXHIBITING DEADLY WEAPON IN A THREATING MANNER",
            "DayOfWeek": "Saturday",
            "Date": "2016-01-23",
            "Time": "11:08",
            "PdDistrict": "CENTRAL",
            "Resolution": "NONE",
            "Address": "1000 Block of HYDE ST",
            "X": "-122.417368206741",
            "Y": "37.7905094151595",
            "Location": "(37.7905094151595, -122.417368206741)",
            "PdId": 16006493812030
        }
    ]
}

Example: Retrieve the status of a failed job

In this example, the Job ID is for a job that did not complete is used.

HTTP request

GET localhost:9047/api/v3/job/23a4bf7e-2544-41f8-7063-f6dc532fc700

Response

{
    "jobState": "FAILED",
    "errorMessage": "Table 'weapons_laws' not found",
    "startedAt": "2019-02-06T20:16:01.939Z",
    "endedAt": "2019-02-06T20:16:01.942Z",
    "queryType": "REST",
    "queueName": "",
    "queueId": "",
    "cancellationReason": ""
}

Example: Retrieve the results of a failed job

In this example, the Job ID is for a job that did not complete is used.

HTTP request

GET localhost:9047/api/v3/job/23a4bf7e-2544-41f8-7063-f6dc532fc700/results

Response

{
    "errorMessage": "Something went wrong",
    "moreInfo": "Can not fetch details for a job that is in [FAILED] state."
}