The HTTP API is the primary means for querying data in TSDB for InfluxDB®. For information about other means to query data, see Command-line interface and Clients.

Note: The examples in this topic are based on curl, which is a command-line tool that uses URLs to transmit data.

To run a query, send a GET request to the /query enpoint. Then, set the URL parameter db to the target database, and set the URL parameter q to the query statement. You can also send a POST request to query data. You can set the same URL parameters as the GET request or set parameters to be part of application/x-www-form-urlencoded. The following example describes how to use the HTTP API to query the databases that are introduced in Use the HTTP API to write data.

curl -G 'https://<Domain name>: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'"

The response from TSDB for InfluxDB® is in JSON format. The query result appears in the results array. If an error occurs, TSDB for InfluxDB® introduces the error details 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
                        ]
                    ]
                }
            ]
        }
    ]
}

Note: When you debug or use curl to query data, you can append pretty=true to the URL to enable well formatted and readable JSON output. In actual production environments, we do not recommend that you use pretty=true because it consumes extra network bandwidth.

Multiple queries

When you send multiple queries to TSDB for InfluxDB® in a single API call, separate the queries with semicolons (;).

curl -G 'https://<Domain name>: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 in a query

Timestamp format

All data in TSDB for InfluxDB® is stored and displayed based on the UTC+0 time zone. By default, timestamps use the UTC+0 time zone, comply with RFC 3339, and are accurate to nanoseconds. For example, 2015-08-04T19:05:14.318570484Z. If you want to return a UNIX timestamp, set the epoch parameter in the request. The value of epoch is a string and can be [h, m, s, ms, u, or ns], which indicate hours, minutes, seconds, milliseconds, microseconds, and nanoseconds. The following example describes how to return a UNIX timestamp that is accurate to seconds.

curl -G 'https://<Domain name>: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

If you set chunked=true in a query, the system returns responses in streamed batches instead of a single response. The system chunks responses by series or by every 10,000 points, whichever occurs first. You can set chunk_size in a query to change the maximum chunk size. The following example describes how to set parameters to chunk responses by every 20,000 points.

curl -G 'https://<Domain name>: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

After you understand how to query data, you can learn how to use InfluxQL. For more information, see Data exploration. For more information about how to query data by using the HTTP API, see HTTP API.

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.