GET /job
Retrieve 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: 0limit
- 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
[info] 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.
[info] 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
[info] 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."
}