On this page

    View a Job

    This API retrieves information about a job.

    Syntax

    OperationURI
    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]
    }
    
    NameTypeDescription
    jobStateStringThe state of the job, will be either PENDING, METADATA_RETRIEVAL, PLANNING, QUEUED, ENGINE_START, EXECUTION_PLANNING, STARTING, RUNNING, COMPLETED, CANCELED, FAILED.
    queryTypeStringThe 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.
    startedAtStringRFC3339 date (example: 2017-10-27T21:08:22.858Z) representing the datetime the query was started.
    endedAtStringRFC3339 date (example: 2017-10-27T21:08:22.858Z) representing the datetime the query ended.
    rowCountNumberIf the query is in COMPLETED state then the number of returned rows will be present.
    accelerationJobAccelerationStatusPresent if the query may have been accelerated.
    errorMessageStringIf 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]
    }
    
    NameTypeDescription
    rowCountNumberThe 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
    

    Note:
    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' \
      -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"
        }
    
    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.

    Note:
    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
    

    Note:
    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' \
      -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"
        }
    
    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."
    }