Query API

You can issue SQL queries in Imply Polaris using the Query API. See Query data by API for more details and examples.

All URIs are relative to https://api.imply.io/v1

Submit SQL query

URL

POST /projects/{projectId}/query/sql

Parameters

Path parameters

  • projectId   type: String   required
    Project ID of your Polaris environment. See the Projects API to get the project ID.

Request body

Submit your query as the value of a query field in the JSON object within the request payload. For example:

{"query" : "SELECT COUNT(*) FROM polaris_table WHERE foo = 'bar'"}

You can optionally specify the following fields in the JSON object:

  • resultFormat: Format of the query results. Select any of the following options:

    • object: Returns a JSON array of JSON objects with the HTTP header Content-Type: application/json.
    • array: Returns a JSON array of JSON arrays with the HTTP header Content-Type: application/json.
    • objectLines: Returns newline-delimited JSON objects with a trailing blank line. Sent with the HTTP header Content-Type: text/plain.
    • arrayLines: Returns newline-delimited JSON arrays with a trailing blank line. Sent with the HTTP header Content-Type: text/plain.
    • csv: Returns comma-separated values with one row per line and a trailing blank line. Sent with the HTTP header Content-Type: text/csv.

  • header: Adds a header row in the query results when set to "true". The fields of the header row are the column names pertaining to the query results. The header row contains null values by default and can hold data types controlled by typesHeader and sqlTypesHeader, if specified.

  • typesHeader: Returns the data types in the header row when set to "true". Requires that header is also set to true. When header and typesHeader are specified as true in the request body, the query result includes an extra row—for example,

    {
    "continent": {
        "type": "STRING"
    },
    "counts": {
        "type": "LONG"
    }
}

  • sqlTypesHeader: Returns the SQL data types in the header row when set to "true". Requires that header is also set to true. When header and sqlTypesHeader are specified as true in the request body, the query result includes an extra row—for example,

    {
    "continent": {
        "sqlType": "VARCHAR"
    },
    "counts": {
        "sqlType": "BIGINT"
    }
}

  • context: JSON object for optional connection context parameters, such as to set the query ID, time zone, and whether to use an approximate algorithm for distinct count. For example:

    {
  "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP '2000-01-01 00:00:00'",
  "context" : {
    "sqlTimeZone" : "America/Los_Angeles"
  }
}

  • parameters: Array of query parameters for parameterized queries. Each element of the array should be a JSON object containing the parameter's SQL data type and value. For example, the following query returns results with timestamps later than 2019-08-21 00:00:00:

    {
    "query": "SELECT continent, COUNT(*) AS counts FROM \"Koalas to the Max\" WHERE __time > ? GROUP BY 1 ORDER BY counts DESC",
    "parameters": [
        {
            "type": "TIMESTAMP",
            "value": "2019-08-21 00:00:00"
        }
    ]
}

Responses


OK.

The request succeeded, and the query result was returned in the response body.


Not Found.

Example body:

{
    "error": {
        "code": "InvalidUri",
        "message": "URI [http://api.imply.io/v1/projects/677b1203-fe4c-4d63-b01c-90254e104dfbc/query/sql] was not found"
    }
}

Sample request

The following example shows how to submit a query using the API:

curl --location --request POST 'https://api.imply.io/v1/projects/149d245a-1207-4946-9057-88c56350000z/query/sql' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Bearer Token>' \
--data-raw '{
    "query": "SELECT continent, COUNT(*) AS counts FROM \"Koalas to the Max\" GROUP BY 1 ORDER BY counts DESC"
}'

Sample response

The following example shows a successful response containing the query result:

[
    {
        "continent": "North America",
        "counts": 241671
    },
    {
        "continent": "Europe",
        "counts": 169433
    },
    {
        "continent": "Oceania",
        "counts": 35905
    },
    {
        "continent": "Asia",
        "counts": 29902
    },
    {
        "continent": "South America",
        "counts": 25336
    },
    {
        "continent": "Africa",
        "counts": 2263
    },
    {
        "continent": "",
        "counts": 922
    }
]
← Performance APINext →