进阶 questdb.com 2026-10-13 06:17:07 · 31 阅读

第5章 QuestDB SQL 参考指南:查询方式与连接协议详解

# 查询与 SQL 概述 你可以通过五种方式查询 QuestDB: - 通过 QuestDB Web Console 查询 - 通过 QuestDB 客户端库查询 - 通过 PostgreSQL 查询 - 通过 REST HTTP API 查询 - 通过 Apache Parquet 查询 为了实现高效清晰的查询,QuestDB 提供了带时间序列扩展的 SQL,让时间序列数据的分析、降采样、处理和读取变得直观灵活。 你可以借助 PostgreSQL 或 REST 生态中现有的驱动和客户端,把查询嵌入到各种应用中。此外,Grafana 等第三方工具也大量依赖查询功能来实现数据可视化。 需要先导入数据?请参阅导入数据概述。 ## QuestDB Web Console Web Console 默认可通过 http://localhost:9000 访问。这个图形界面让编写、返回和绘制查询结果变得非常简单,支持自动补全、语法高亮、错误提示等功能。 如果你想测试一条查询,或以最简洁直接的方式与数据交互,推荐使用 Web Console 执行查询。 点击放大 例如,点击下面代码片段中的 Demo this query,即可在我们的公共演示实例和 Web Console 中运行查询: 用 SQL 在时间中导航 Demo this query SELECT
timestamp, symbol,
first(price) AS open,
last(price) AS close,
min(price),
max(price),
sum(amount) AS volume
FROM trades
WHERE timestamp > dateadd('d', -1, now())
SAMPLE BY 15m;
如果你在本文档中看到“在 Demo 中运行此查询”标记于其他代码片段旁,说明这些查询可以针对演示实例执行。 QuestDB 客户端库​ 官方客户端库使用 QuestDB 线协议(QWP),这是一种二进制协议,可在单一连接和单一配置字符串中同时传输数据摄取和查询流量。这是从应用程序获取 QuestDB 数据的最快方式。 结果以流式方式返回,而非一次性到达。服务器在生成数据时即发送批次,因此应用程序可以在结果尾部仍在计算时就开始处理头部数据,大于内存容量的结果也无需完全实例化。 连接具有自愈能力。当连接断开且副本可用时,客户端会自动重连并在另一副本上重试,无需应用程序介入。如果查询失败后从头重试,只要你将整个结果实例化,这一过程对上层就是透明的。 Rust、C++ 和 Python 客户端以 Arrow 记录批次形式返回结果。这正是 pandas、Polars 和 DuckDB 的原生内存布局,因此查询结果可直接转换为 DataFrame,无需逐行转换。 请参阅 Connect 概述,查看各语言指南以及当前支持 QWP 的客户端。 PostgreSQL​ 通过默认端口 8812 使用 PostgreSQL 端点查询 QuestDB。 有关使用 PostgreSQL 客户端连接 QuestDB 的详细信息,请参阅 PGWire 客户端概述。 以下提供多种语言的简短示例。 Python import psycopg as pg import time # 连接到现有的 QuestDB 实例 conn_str = 'user=admin password=quest host=127.0.0.1 port=8812 dbname=qdb' with pg.connect(conn_str, autocommit=True) as connection: # 打开游标以执行数据库操作 with connection.cursor() as cur: # 查询数据库并获取 Python 对象形式的数据 cur.execute('SELECT * FROM trades_pg;') records = cur.fetchall() for row in records: print(row) # 连接现在已关闭 Java package com.myco; import java.sql.*; import java.util.Properties; public class App { public static void main(String[] args) throws SQLException { Properties properties = new Properties(); properties.setProperty("user", "admin"); properties.setProperty("password", "quest"); properties.setProperty("sslmode", "disable"); 下面展示了使用 JDBC、Node.js、Go 和 C/C++ 连接数据库的示例代码: final Connection connection = DriverManager.getConnection(
"jdbc:postgresql://localhost:8812/qdb", properties);
try (PreparedStatement preparedStatement = connection.prepareStatement(
"SELECT x FROM long_sequence(5);")) {
try (ResultSet rs = preparedStatement.executeQuery()) {
while (rs.next()) {
System.out.println(rs.getLong(1));
}
}
}
connection.close();
}
}

"use strict"

const { Client } = require("pg")

const start = async () => {
const client = new Client({
database: "qdb",
host: "127.0.0.1",
password: "quest",
port: 8812,
user: "admin",
})
await client.connect()

const res = await client.query("SELECT x FROM long_sequence(5);")

console.log(res.rows)

await client.end()
}

start().catch(console.error)
package main

import (
"database/sql"
"fmt"

_ "github.com/lib/pq"
)

const (
host = "localhost"
port = 8812
user = "admin"
password = "quest"
dbname = "qdb"
)

func main() {
connStr := fmt.Sprintf(
"host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
host, port, user, password, dbname)
db, err := sql.Open("postgres", connStr)
checkErr(err)
defer db.Close()

stmt, err := db.Prepare("SELECT x FROM long_sequence(5);")
checkErr(err)
defer stmt.Close()

rows, err := stmt.Query()
checkErr(err)
defer rows.Close()

var num string
for rows.Next() {
err = rows.Scan(&num)
checkErr(err)
fmt.Println(num)
}

err = rows.Err()
checkErr(err)
}

func checkErr(err error) {
if err != nil {
panic(err)
}
}
// compile with
// g++ libpq_example.c -o libpq_example.exe -I pgsql\include -L dev\pgsql\lib
// -std=c++17 -lpthread -lpq
#include
#include
#include

void do_exit(PGconn *conn) {
PQfinish(conn);
exit(1);
}

int main() {
PGconn *conn = PQconnectdb(
"host=localhost user=admin password=quest port=8812 dbname=testdb");
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr, "Connection to database failed: %s\n",
PQerrorMessage(conn));
do_exit(conn);
}
PGresult *res = PQexec(conn, "SELECT x FROM long_sequence(5);");
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
printf("No data retrieved\n");
PQclear(res);
do_exit(conn);
}
int rows = PQntuples(res);
for (int i = 0; i < rows; i++) {
printf("%s\n", PQgetvalue(res, i, 0));
}
PQclear(res);
PQfinish(conn);
return 0;
}
using Npgsql;
string username = "admin";
string password = "quest";
string database = "qdb";
int port = 8812;
var connectionString = $@"host=localhost;port={port};username={username};password={password};
database={database};ServerCompatibilityMode=NoTypeLoading;";
await using NpgsqlConnection connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();

var sql = "SELECT x FROM long_sequence(5);";

await using NpgsqlCommand command = new NpgsqlCommand(sql, connection);
await using (var reader = await command.ExecuteReaderAsync()) {
while (await reader.ReadAsync())
{
var x = reader.GetInt64(0);
}
}
require 'pg'
begin
conn =PG.connect( host: "127.0.0.1", port: 8812, dbname: 'qdb',
user: 'admin', password: 'quest' )
rows = conn.exec 'SELECT x FROM long_sequence(5);'
rows.each do |row|
puts row
end
rescue PG::Error => e
puts e.message
ensure
conn.close if conn
end

function exceptions_error_handler($severity, $message, $filename, $lineno) {
throw new ErrorException($message, 0, $severity, $filename, $lineno);
}

set_error_handler('exceptions_error_handler');
$db_conn = null;

try {
$db_conn = pg_connect(" host = 'localhost' port=8812 dbname = 'qdb' user = 'admin' password = 'quest' ");
$result = pg_query($db_conn, 'SELECT x FROM long_sequence(5);' );
while ($row = pg_fetch_assoc($result) ){
print_r($row);
}
pg_free_result($result);
} catch (Exception $e) {
echo 'Caught exception: ', $e->getMessage(), "\n";
} finally {
if (!is_null($db_conn)) {
pg_close($db_conn);
}
}

?> 延伸阅读 有关如何使用 PostgreSQL 客户端连接 QuestDB 的详细信息,请参阅 PGWire Client 概述。 REST HTTP API QuestDB 提供 REST API,以兼容各类库和工具。 REST API 通过 9000 端口访问,支持以下可查询的端点: 有关内容类型、查询参数等详细信息,请参阅 REST HTTP API 参考文档。 端点 | HTTP 方法 | 描述 | REST HTTP API 参考 /exp?query=.. | GET | 将 SQL 查询导出为 CSV | 参考文档 /execute?query=.. | GET | 运行 SQL 查询并返回 JSON 结果集 | 参考文档 /exp:SQL 查询转 CSV /exp 端点允许使用 SQL select 语句查询数据库,并以 CSV 格式获取结果。 若需以 JSON 格式获取结果,请改用随后介绍的 /execute 端点。 cURL | Python curl -G --data-urlencode \
"query=SELECT * FROM example_table2 LIMIT 3" \
http://localhost:9000/exp
"col1","col2","col3"
"a",10.5,true
"b",100.0,false
"c",,true
| import requests

resp = requests.get(
'http://localhost:9000/exp',
{
'query': 'SELECT * FROM example_table2',
'limit': '3,6' # 第 3、4、5 行
})
print(resp.text)
"col1","col2","col3"
"d",20.5,true
"e",200.0,false
"f",,true
/execute:SQL 查询转 JSON /execute 端点接收 SQL 查询并以 JSON 格式返回结果。该端点此前名为 /exec,虽已弃用但仍可正常工作。 这与返回 CSV 结果的 /exp 端点类似。 查询数据 cURL | Python | NodeJS | Go curl -G \
--data-urlencode "query=SELECT x FROM long_sequence(5);" \
http://localhost:9000/api/v1/sql/execute
| import sys
import requests

host = 'http://localhost:9000'

sql_query = "select * from long_sequence(10)"

try:
response = requests.get(
host + '/exec',
params={'query': sql_query}).json()
for row in response['dataset']:
print(row[0])
except requests.exceptions.RequestException as e:
print(f'Error: {e}', file=sys.stderr)
| const fetch = require("node-fetch")

const HOST = "http://localhost:9000"

| JSON 响应包含原始查询语句、描述结果架构的 "columns" 键、行数 "count" 以及包含结果的 "dataset"。 {
"query": "SELECT x FROM long_sequence(5);",
"columns": [{ "name": "x", "type": "LONG" }],
"dataset": [[1], [2], [3], [4], [5]],
"count": 5
}
```html async function run() {
try {
const query = "SELECT x FROM long_sequence(5);"

const response = await fetch(
`${HOST}/exec?query=${encodeURIComponent(query)}`,
)
const json = await response.json()

console.log(json)
} catch (error) {
console.log(error)
}
}

run()
package main

import (
"fmt"
"io/ioutil"
"log"
"net/http"
"net/url"
)

func main() {
u, err := url.Parse("http://localhost:9000")
checkErr(err)

u.Path += "exec"
params := url.Values{}
params.Add("query", "SELECT x FROM long_sequence(5);")
u.RawQuery = params.Encode()
url := fmt.Sprintf("%v", u)

res, err := http.Get(url)
checkErr(err)

defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
checkErr(err)

log.Println(string(body))
}

func checkErr(err error) {
if err != nil {
panic(err)
}
}
或者,可以使用 /exec 端点创建表,并通过 INSERT 语句为其插入数据: cURLNodeJSPython# 创建表
curl -G \
--data-urlencode "query=CREATE TABLE IF NOT EXISTS trades(name VARCHAR, value INT)" \
http://localhost:9000/api/v1/sql/execute

# 插入一行数据
curl -G \
--data-urlencode "query=INSERT INTO trades VALUES('abc', 123456)" \
http://localhost:9000/api/v1/sql/execute

# 更新一行数据
curl -G \
--data-urlencode "query=UPDATE trades SET value = 9876 WHERE name = 'abc'" \
http://localhost:9000/api/v1/sql/execute
可以通过 npm i node-fetch 安装 node-fetch 包。const fetch = require("node-fetch");

const HOST = "http://localhost:9000";

async function createTable() {
try {
const query = "CREATE TABLE IF NOT EXISTS trades (name VARCHAR, value INT)";

const response = await fetch(
`${HOST}/exec?query=${encodeURIComponent(query)}`,
);
const json = await response.json();

console.log(json);
} catch (error) {
console.log(error);
}
}

async function insertData() {
try {
const query = "INSERT INTO trades VALUES('abc', 123456)";

const response = await fetch(
`${HOST}/exec?query=${encodeURIComponent(query)}`,
);
const json = await response.json();

console.log(json);
} catch (error) {
``` console.log(error);
}
}

async function updateData() {
try {
const query = "UPDATE trades SET value = 9876 WHERE name = 'abc'";

const response = await fetch(
`${HOST}/exec?query=${encodeURIComponent(query)}`,
);
const json = await response.json();

console.log(json);
} catch (error) {
console.log(error);
}
}

createTable().then(insertData).then(updateData);
import requests
import json

host = 'http://localhost:9000'

def run_query(sql_query):
query_params = {'query': sql_query, 'fmt' : 'json'}
try:
response = requests.get(host + '/exec', params=query_params)
json_response = json.loads(response.text)
print(json_response)
except requests.exceptions.RequestException as e:
print("Error: %s" % (e))

# 创建表
run_query("CREATE TABLE IF NOT EXISTS trades (name VARCHAR, value INT)")
# 插入行
run_query("INSERT INTO trades VALUES('abc', 123456)")
# 更新行
run_query("UPDATE trades SET value = 9876 WHERE name = 'abc'")
Apache Parquet​ QuestDB 可以读取并查询 Parquet 文件。 QuestDB 自带一个示例 Parquet 文件 trades.parquet,可以通过 read_parquet 函数进行查询。 示例: read_parquet exampleSELECT
*
FROM
read_parquet('trades.parquet')
WHERE
side = 'buy';
trades.parquet 文件位于 QuestDB 根目录下的 import 子目录中。你可以将自定义的 Parquet 文件放入 import 目录,并通过 read_parquet() 函数进行查询。若要更改允许访问的目录,请设置 cairo.sql.copy.root 配置项。更多详情,请参阅 Parquet 文档。 接下来做什么? 好,现在开始查数据。 无论你使用 Web Console、PostgreSQL 还是 REST HTTP(或者组合使用),QuestDB 的查询构造功能都非常丰富。 为了巩固基础并了解 QuestDB 的独特之处,建议关注以下内容: 数据类型 SQL 执行顺序 此外,以下是一些我们最常用、功能最强大的核心语法: 窗口函数(Window functions)是强大的分析工具。 聚合函数——聚合(Aggregations)至关重要! 日期和时间运算符——学习如何操作日期与时间。 SAMPLE BY——按指定的时间间隔(从一年到微秒)将数据汇总为分块。 WHERE IN——将时间范围压缩为简洁的区间。 LATEST ON——获取表中多个序列的最新值。 ASOF JOIN——基于时间接近性在不同序列之间关联时间戳,无需额外索引。 物化视图(Materialized Views)——预计算复杂查询,以获取最优性能。 想要更多可视化效果? 探索 Grafana 快速进入 Web Console

评论 (0)