通过HTTP API查询数据 - 时间序列数据库 TSDB

HTTP API是TSDB For InfluxDB®查询数据的主要方式。

其它查询数据的方法可查阅文档命令行界面和客户端。

说明

本章节中的示例使用了curl,一种通过URL来传输数据的命令行工具。

执行一个查询，需要发送一个GET请求到/query路径，设置URL的参数db为目标数据库，并设置URL的参数q为查询语句。您也可以发送POST请求，参数设置跟GET请求一样，作为URL的参数或者作为application/x-www-form-urlencoded类型的内容的一部分。下面的例子展示如何使用HTTP API来查询数据库，这些数据库的名字在文档通过HTTP API写入数据中已经出现过了。

curl -G 'https://<网络地址>:3242/query?u=<账号名称>&p=<密码>&pretty=true' --data-urlencode "db=mydb" --data-urlencode "q=SELECT \"value\" FROM \"cpu_load_short\" WHERE \"region\"='us-west'"

TSDB For InfluxDB®的返回值是JSON格式的，您查询的结果放在results数组中。如果发生错误，TSDB For InfluxDB®会在关键字error后面解释错误发生的原因。

{
    "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
                        ]
                    ]
                }
            ]
        }
    ]
}

说明

注释：添加pretty=true到URL里可以使JSON的输出更美观，可读性更好，这在调试或者直接使用curl等工具查询时很有用，但是在实际生产中不建议使用，因为它会消耗不必要的网络带宽。

多个查询

在单个API调用中向TSDB For InfluxDB®发送多个查询，只需使用分号将每个查询分隔开，例如：

curl -G 'https://<网络地址>:3242/query?u=<账号名称>&p=<密码>&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'"

系统会返回：

{
    "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
                        ]
                    ]
                }
            ]
        }
    ]
}

查询数据时的其它选项

时间戳格式

TSDB For InfluxDB®中的所有数据都是以UTC时间来存储和展示的。时间戳默认按RFC3339格式的UTC时间返回，并精确到纳秒级，例如2015-08-04T19:05:14.318570484Z。如果您想要返回Unix格式的时间戳，请在您的请求中设置参数epoch，其中，epoch的值是字符串类型，可以是[h, m, s, ms, u, ns]之一，分别代表小时、分钟、秒、毫秒、微秒和纳秒。例如，时间戳按Unix格式返回，精确到秒：

curl -G 'https://<网络地址>:3242/query?u=<账号名称>&p=<密码>' --data-urlencode "db=mydb" --data-urlencode "epoch=s" --data-urlencode "q=SELECT \"value\" FROM \"cpu_load_short\" WHERE \"region\"='us-west'"

分块

通过设置查询参数chunked=true，可以开启分块（Chunking），使结果流式批量地返回，而不是一次性全部返回。返回的结果可以按时间线或者按每10,000个数据点分块（哪个条件最先满足就以哪个条件来分块）。如果需要改变分块大小的最大值，请将查询参数chunk_size设为您需要的大小。例如，返回结果时，如果按每20,000个数据点进行分块，可以这样设置：

curl -G 'https://<网络地址>:3242/query?u=<账号名称>&p=<密码>' --data-urlencode "db=deluge" --data-urlencode "chunked=true" --data-urlencode "chunk_size=20000" --data-urlencode "q=SELECT * FROM liters"

InfluxQL

现在您已经知道了如何查询数据，如有需要，请查阅文档数据探索来熟悉InfluxQL的用法。想更多了解如何通过HTTP API查询数据，请查看文档HTTP API。

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