使用 database/sql 查询
Go SDK 通过标准库
database/sql
database/sql
执行查询和 DML。本文介绍 DSN 参数、查询与写入、参数绑定、SQL 参数设置、超时与取消,以及以 Arrow 格式读取结果。安装和第一个查询程序见
Go SDK 简介。
连接字符串(DSN)
<username>:<password>@<protocol>(<service>)/<schema>?virtualCluster=<vcluster>&workspace=<workspace>&instance=<instance>[&<参数>=<值>...]
| 参数 | 是否必填 | 说明 |
|---|
username
username | 是 | 登录用户名 |
password
password | 是 | 登录密码。使用 magic_token
magic_token 认证时可以不填 |
protocol
protocol | 否 | https
https 或 http
http 。主版本从 v0.0.20
v0.0.20 开始可以省略,默认 https
https ,例如 <username>:<password>@(<service>)/...
<username>:<password>@(<service>)/... 。 ⚠️ v0.0.19
v0.0.19 及更早版本中省略协议时,请求会失败并返回 unsupported protocol scheme ""
unsupported protocol scheme "" 。使用这些版本或兼容版本时请显式填写 |
service
service | 是 | Lakehouse 服务地址,例如 cn-shanghai-alicloud.api.clickzetta.com
cn-shanghai-alicloud.api.clickzetta.com ;DSN 中不要重复填写 https://
https:// 。所有地域见 云服务和地域 |
schema
schema | 否 | 默认 SCHEMA;不填写时使用 public
public |
virtualCluster
virtualCluster | 是 | 默认计算集群名称,也可以写作 vc
vc |
workspace
workspace | 是 | 工作空间名称 |
instance
instance | 是 | Lakehouse 服务实例名称 |
可选参数:
| 参数 | 默认值 | 说明 |
|---|
magic_token
magic_token | 无 | 使用已有的 token 认证,跳过用户名密码登录。也可以写作 token
token |
sdk.query.max.retries
sdk.query.max.retries | 10
10 | 提交作业和获取结果时的最大重试次数 |
separate_params
separate_params | false
false | 为 true
true 时,INSERT
INSERT 的批量参数以 Arrow 二进制格式单独发送,不拼接进 SQL 文本。适合大批量参数写入 |
cz.sql.string.literal.escape.mode
cz.sql.string.literal.escape.mode | backslash
backslash | 驱动拼接字符串参数时的转义方式,见 字符串转义 |
参数值需要进行 URL 编码。
前置准备
本文以及 批量写入数据(Bulkload)、使用 GORM 中的示例共用以下表和数据。在 DSN 指定的 SCHEMA 中执行:
CREATE TABLE doc_go_orders (
id BIGINT NOT NULL,
name STRING,
amount INT,
cost DECIMAL(10, 2)
);
CREATE TABLE doc_go_orders_archive (
id BIGINT NOT NULL,
name STRING,
amount INT,
cost DECIMAL(10, 2)
);
CREATE TABLE doc_go_tags (
id BIGINT,
tags ARRAY<INT>
);
INSERT INTO doc_go_orders VALUES
(1, 'Alice', 120, 18.00),
(2, 'Bob', 80, 12.50),
(3, 'Carol', 260, 39.00);
SELECT * FROM doc_go_orders ORDER BY id
SELECT * FROM doc_go_orders ORDER BY id
的结果:
| id | name | amount | cost |
|---|
| 1 | Alice | 120 | 18.00 |
| 2 | Bob | 80 | 12.50 |
| 3 | Carol | 260 | 39.00 |
示例中的
db
db
是
sql.Open("clickzetta", dsn)
sql.Open("clickzetta", dsn)
返回的
*sql.DB
*sql.DB
,
ctx
ctx
是
context.Context
context.Context
。
查询与写入
rows, err := db.QueryContext(ctx, "SELECT id, name FROM doc_go_orders WHERE amount > ? ORDER BY id LIMIT 10", 100)
if err != nil {
log.Fatal(err)
}
defer rows.Close()
for rows.Next() {
var id int64
var name string
if err := rows.Scan(&id, &name); err != nil {
log.Fatal(err)
}
fmt.Println(id, name)
}
if err := rows.Err(); err != nil {
log.Fatal(err)
}
_, err = db.ExecContext(ctx, "INSERT INTO doc_go_orders (id, name, amount) VALUES (?, ?, ?)", 4, "O'Brien", 200)
if err != nil {
log.Fatal(err)
}
查询输出
amount
amount
大于 100 的订单:
1 Alice
3 Carol
INSERT
INSERT
执行后,
SELECT * FROM doc_go_orders WHERE id = 4
SELECT * FROM doc_go_orders WHERE id = 4
的结果如下。未写入的
cost
cost
列为 NULL,
'
'
按原样写入:
| id | name | amount | cost |
|---|
| 4 | O'Brien | 200 | NULL |
⚠️ 注意:
INSERT
INSERT
等 DML 返回的
sql.Result
sql.Result
中,
RowsAffected()
RowsAffected()
为
0
0
,不代表实际写入的行数。需要确认写入结果时请查询目标表。
参数绑定
SQL 中的
?
?
占位符由驱动替换为对应参数的字面量后再提交。驱动按以下规则生成字面量:
| Go 类型 | 生成的 SQL |
|---|
| 整数、浮点数 | 数值字面量。NaN
NaN 和无穷大会返回错误 |
string
string | 加引号并转义的字符串。必须是合法的 UTF-8,否则返回错误;二进制数据请使用 []byte
[]byte |
[]byte
[]byte | 十六进制 BINARY 字面量 X'...'
X'...' |
time.Time
time.Time | timestamp 'YYYY-MM-DD HH:MM:SS[.ffffff]±HH:MM'
timestamp 'YYYY-MM-DD HH:MM:SS[.ffffff]±HH:MM' ,带时区偏移,精度最高到微秒 |
nil
nil 、sql.NullString
sql.NullString 等 | 值为空时生成 NULL
NULL |
goclickzetta.RawSQLValue
goclickzetta.RawSQLValue | 原样拼接,用于 ARRAY、MAP、STRUCT 等复杂类型 |
复杂类型使用
RawSQLValue
RawSQLValue
传入:
_, err := db.ExecContext(ctx, "INSERT INTO doc_go_tags VALUES (?, ?)", 1, goclickzetta.RawSQLValue("array(1,2,3)"))
执行
SELECT id, tags FROM doc_go_tags
SELECT id, tags FROM doc_go_tags
,把两列扫描到
any
any
类型的变量后用
fmt.Println
fmt.Println
打印:
1 [1 2 3]
⚠️ 注意:
RawSQLValue
RawSQLValue
的内容会被当作 SQL 执行,不要用不可信的输入构造
RawSQLValue
RawSQLValue
。
字符串转义
字符串默认按
backslash
backslash
方式转义:
'
'
转为
\'
\'
,
\
\
转为
\\
\\
。驱动会把所用的转义方式作为 SQL 参数告知服务端。
可以把
cz.sql.string.literal.escape.mode
cz.sql.string.literal.escape.mode
设为
quote
quote
,改为
quote
quote
方式(
'
'
转为
''
''
)。该参数只能通过 DSN 或
WithDriverFlags
WithDriverFlags
设置。写在 SQL 前面不起作用:驱动会用 DSN 或 context 中的值覆盖它。
⚠️ 注意:只应在确认服务端支持该参数时使用
quote
quote
。不支持时,
O'Brien
O'Brien
会被写成
OBrien
OBrien
,数据被静默改写,不会返回错误。
验证方法:通过 context 设置
quote
quote
后执行
SELECT 'O''Brien'
SELECT 'O''Brien'
。返回
O'Brien
O'Brien
说明服务端支持;返回
OBrien
OBrien
说明不支持,请继续使用默认的
backslash
backslash
方式。
qctx := goclickzetta.WithDriverFlags(ctx, goclickzetta.DriverFlags{
"cz.sql.string.literal.escape.mode": "quote",
})
var s string
if err := db.QueryRowContext(qctx, "SELECT 'O''Brien'").Scan(&s); err != nil {
log.Fatal(err)
}
fmt.Println(s)
在不支持
quote
quote
的服务端上,输出为:
OBrien
设置 SQL 参数
在 JDBC 中通过
set
set
命令设置的 SQL 参数,在 Go SDK 中有两种传递方式。支持的参数请参考
参数管理。
写在 SQL 前面:用
<参数>=<值>;
<参数>=<值>;
的形式写在语句前,不需要
set
set
关键字。可以写多个参数,最后一条是要执行的语句:
var ts time.Time
err := db.QueryRowContext(ctx, "cz.sql.timezone=Asia/Shanghai;SELECT current_timestamp()").Scan(&ts)
ts
ts
是一个时间点,打印时时区为 UTC,例如
2026-11-16 12:38:57.555467 +0000 UTC
2026-11-16 12:38:57.555467 +0000 UTC
。需要按特定时区显示时调用
ts.In()
ts.In()
转换。
通过 context 传递:适合给一组语句统一设置参数:
ctx := goclickzetta.WithDriverFlags(context.Background(), goclickzetta.DriverFlags{
"cz.sql.timezone": "Asia/Shanghai",
})
rows, err := db.QueryContext(ctx, "SELECT id, name, amount FROM doc_go_orders ORDER BY id LIMIT 10")
通过 context 还可以临时切换
schema
schema
、
catalog
catalog
和
virtualCluster
virtualCluster
,只对这次调用生效。
超时与取消
| 方式 | 作用 |
|---|
context.WithTimeout
context.WithTimeout | 只控制客户端等待结果的时间。超时后 SDK 停止等待并返回错误,服务端作业继续运行。 ⚠️ v0.0.20
v0.0.20 及更早版本和兼容版本中,小于 30 秒的超时不生效,约 30 秒后才返回 |
sdk.job.timeout
sdk.job.timeout | 作业超过指定秒数仍未结束时,SDK 取消服务端作业并返回错误 |
Cancel
Cancel 、CancelJob
CancelJob | 主动取消服务端作业 |
sdk.job.timeout
sdk.job.timeout
是 SDK 自身的参数,单位为秒,写在 SQL 前面传递,不会发送给服务端。从
v0.0.21
v0.0.21
开始,计时从提交作业时算起,作业在设置的秒数后被取消。例如设置为
5
5
时,长时间运行的作业约在 5 秒后被取消,
ExecContext
ExecContext
返回
job timeout, jobid: <作业 ID>
job timeout, jobid: <作业 ID>
。
⚠️ 注意:
v0.0.20
v0.0.20
及更早版本和兼容版本中,计时从 SDK 开始轮询作业结果时算起,而提交作业时 SDK 会先等待服务端最多 30 秒,因此作业实际被取消的时间约为 30 秒加上设置的值,例如设置为
5
5
时约 35 秒。从这些版本升级到
v0.0.21
v0.0.21
后,作业会比之前早约 30 秒被取消,请确认设置的值是否仍然合适。
以下语句为归档作业设置 600 秒的时限:
_, err := db.ExecContext(ctx, "sdk.job.timeout=600;INSERT INTO doc_go_orders_archive SELECT * FROM doc_go_orders")
作业在时限内完成,
err
err
为
nil
nil
,
doc_go_orders_archive
doc_go_orders_archive
中写入了
doc_go_orders
doc_go_orders
的全部行。
*goclickzetta.ClickzettaConn
*goclickzetta.ClickzettaConn
提供两个取消方法,参数
userAgent
userAgent
用于标识取消的来源,传空字符串时使用默认值:
Cancel(userAgent string) error
Cancel(userAgent string) error
:取消该连接上正在执行的作业。
CancelJob(jobID string, userAgent string) error
CancelJob(jobID string, userAgent string) error
:按作业 ID 取消作业。
database/sql
database/sql
在执行语句期间会锁定连接,此时在另一个 goroutine 中调用
conn.Raw
conn.Raw
会一直等到语句结束,无法取消正在执行的作业。因此需要在
Raw
Raw
回调中通过驱动连接执行语句,并在定时器或其他 goroutine 中调用
Cancel
Cancel
:
conn, err := db.Conn(ctx)
if err != nil {
log.Fatal(err)
}
defer conn.Close()
err = conn.Raw(func(dc any) error {
cz := dc.(*goclickzetta.ClickzettaConn)
// 5 秒后取消该连接上正在执行的作业
timer := time.AfterFunc(5*time.Second, func() {
if err := cz.Cancel("my-app"); err != nil {
log.Println("cancel:", err)
}
})
defer timer.Stop()
// 一个需要较长时间的查询:4 × 1010 行的笛卡尔积
_, err := cz.ExecContext(ctx, "SELECT sum(a*b) FROM (SELECT explode(sequence(1,200000)) a) x CROSS JOIN (SELECT explode(sequence(1,200000)) b) y", nil)
return err
})
fmt.Println(err)
约 5 秒后输出:
job cancelled, jobid: <作业 ID>
作业被取消后,
ExecContext
ExecContext
返回上述错误,连接仍可继续使用。作业在取消前已经结束时,
Cancel
Cancel
不起作用,
ExecContext
ExecContext
正常返回。已知作业 ID 时,也可以在任意连接上调用
CancelJob
CancelJob
取消该作业。
读取 Arrow 格式结果
需要直接处理列式数据时,可以用
QueryArrowStream
QueryArrowStream
获取 Arrow RecordReader,避免逐行转换的开销:
conn, err := db.Conn(ctx)
if err != nil {
log.Fatal(err)
}
defer conn.Close()
err = conn.Raw(func(dc any) error {
reader, err := dc.(*goclickzetta.ClickzettaConn).QueryArrowStream(ctx, "SELECT * FROM doc_go_orders", nil)
if err != nil {
return err
}
defer reader.Release()
for reader.Next() {
record := reader.Record()
fmt.Println(record.NumRows())
}
return reader.Err()
})
每次
reader.Next()
reader.Next()
返回一批数据,输出该批的行数。批次的划分由服务端决定,各批行数之和等于结果的总行数。
返回值类型为
github.com/apache/arrow-go/v18/arrow/array.RecordReader
github.com/apache/arrow-go/v18/arrow/array.RecordReader
。该接口只在主版本中提供。
作业来源信息
从
v0.0.19
v0.0.19
(Arrow v12 兼容版
v0.0.20-arrow12
v0.0.20-arrow12
,无 Arrow 版
v0.0.12-csv
v0.0.12-csv
)开始,SDK 提交的每个 SQL 作业都会携带客户端信息,便于在作业历史中区分来源和排查问题: