The HTTP API is the primary way to query data from TSDB for InfluxDB®.
For other methods to query data, see the command-line interface and client documentation.
The examples in this section use curl, a command line interface for transferring data with URLs.
To execute a query, send a GET request to the /query path. Set the db URL parameter to the target database and the q URL parameter to the search statement. You can also send a POST request. The parameters are the same as for a GET request and can be sent as URL parameters or as part of an application/x-www-form-urlencoded body. The following example shows how to use the HTTP API to query the databases that are used in the Write data using the HTTP API document.
curl -G 'https://<network address>:3242/query?u=<username>&p=<password>&pretty=true' --data-urlencode "db=mydb" --data-urlencode "q=SELECT \"value\" FROM \"cpu_load_short\" WHERE \"region\"='us-west'"TSDB for InfluxDB® returns values in JSON format. The query results are in the results array. If an error occurs, TSDB for InfluxDB® returns an error message in the error field.
{
"results": [
{
"statement_id": 0,
"series": [
{
"name": "cpu_load_short",
"columns": [
"time",
"value"
],
"values": [
[
"2015-01-29T21:55:43.702900257Z",
2
],
[
"2015-01-29T21:55:43.702900257Z",
0.55
],
[
"2015-06-11T20:46:02Z",
0.64
]
]
}
]
}
]
}You can add `pretty=true` to the URL to make the JSON output easier to read. This is useful for debugging or for querying directly with tools such as curl. Do not use this parameter in production because it consumes unnecessary network bandwidth.
Multiple queries
To send multiple queries to TSDB for InfluxDB® in a single API call, separate each query with a semicolon. For example:
curl -G 'https://<network address>:3242/query?u=<username>&p=<password>&pretty=true' --data-urlencode "db=mydb" --data-urlencode "q=SELECT \"value\" FROM \"cpu_load_short\" WHERE \"region\"='us-west';SELECT count(\"value\") FROM \"cpu_load_short\" WHERE \"region\"='us-west'"The system returns:
{
"results": [
{
"statement_id": 0,
"series": [
{
"name": "cpu_load_short",
"columns": [
"time",
"value"
],
"values": [
[
"2015-01-29T21:55:43.702900257Z",
2
],
[
"2015-01-29T21:55:43.702900257Z",
0.55
],
[
"2015-06-11T20:46:02Z",
0.64
]
]
}
]
},
{
"statement_id": 1,
"series": [
{
"name": "cpu_load_short",
"columns": [
"time",
"count"
],
"values": [
[
"1970-01-01T00:00:00Z",
3
]
]
}
]
}
]
}Other options for querying data
Timestamp format
All data in TSDB for InfluxDB® is stored and displayed in UTC. By default, timestamps are returned in RFC3339 UTC format with nanosecond precision, such as 2015-08-04T19:05:14.318570484Z. To return a UNIX timestamp, set the epoch parameter in your request. The value of epoch is a string that specifies the precision: `h` for hours, `m` for minutes, `s` for seconds, `ms` for milliseconds, `u` for microseconds, or `ns` for nanoseconds. For example, to return a timestamp in UNIX format with second precision:
curl -G 'https://<network address>:3242/query?u=<username>&p=<password>' --data-urlencode "db=mydb" --data-urlencode "epoch=s" --data-urlencode "q=SELECT \"value\" FROM \"cpu_load_short\" WHERE \"region\"='us-west'"Chunking
You can enable chunking by setting the chunked=true query parameter. This streams results in batches instead of in a single response. Results are chunked by series or by every 10,000 data points, whichever condition is met first. To change the maximum chunk size, set the chunk_size query parameter to the desired size. For example, to return results in chunks of 20,000 data points, set the parameters as follows:
curl -G 'https://<network address>:3242/query?u=<username>&p=<password>' --data-urlencode "db=deluge" --data-urlencode "chunked=true" --data-urlencode "chunk_size=20000" --data-urlencode "q=SELECT * FROM liters"InfluxQL
Now that you know how to query data, see the Data exploration document to learn about InfluxQL. For more information about querying data with the HTTP API, see the HTTP API document.
InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.